other misc fixes

[wxWidgets.git] / interface / archive.h

diff --git a/interface/archive.h b/interface/archive.h
index 7fb18d7c958bc18ae75bd2d1cea3c9b08b87c8e7..cb2069dc6057b9d10042def7503499b759776014 100644 (file)
--- a/interface/archive.h
+++ b/interface/archive.h
@@ -10,7 +10,7 @@
     @class wxArchiveInputStream
     @wxheader{archive.h}
 
     @class wxArchiveInputStream
     @wxheader{archive.h}
 

-    An abstract base class which serves as a common interface to
+    This is an abstract base class which serves as a common interface to

     archive input streams such as wxZipInputStream.
 
     wxArchiveInputStream::GetNextEntry returns an wxArchiveEntry object containing
     archive input streams such as wxZipInputStream.
 
     wxArchiveInputStream::GetNextEntry returns an wxArchiveEntry object containing


@@ -34,7 +34,7 @@ public:
         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();
+    virtual bool CloseEntry() = 0;

 
     /**
         Closes the current entry if one is open, then reads the meta-data for
 
     /**
         Closes the current entry if one is open, then reads the meta-data for


@@ -50,7 +50,7 @@ public:
         @a entry must be from the same archive file that this wxArchiveInputStream
         is reading, and it must be reading it from a seekable stream.
     */
         @a entry must be from the same archive file that this wxArchiveInputStream
         is reading, and it must be reading it from a seekable stream.
     */

-    bool OpenEntry(wxArchiveEntry& entry);
+    virtual bool OpenEntry(wxArchiveEntry& entry) = 0;

 };
 
 
 };
 
 


@@ -59,7 +59,7 @@ public:
     @class wxArchiveOutputStream
     @wxheader{archive.h}
 
     @class wxArchiveOutputStream
     @wxheader{archive.h}
 

-    An abstract base class which serves as a common interface to
+    This is an abstract base class which serves as a common interface to

     archive output streams such as wxZipOutputStream.
 
     wxArchiveOutputStream::PutNextEntry is used to create a new entry in the
     archive output streams such as wxZipOutputStream.
 
     wxArchiveOutputStream::PutNextEntry is used to create a new entry in the


@@ -77,20 +77,22 @@ public:
     /**
         Calls Close() if it has not already been called.
     */
     /**
         Calls Close() if it has not already been called.
     */

-    ~wxArchiveOutputStream();
+    virtual ~wxArchiveOutputStream();

 
     /**
         Closes the archive, returning @true if it was successfully written.
         Called by the destructor if not called explicitly.
 
     /**
         Closes the archive, returning @true if it was successfully written.
         Called by the destructor if not called explicitly.

+
+        @see wxOutputStream::Close()

     */
     */

-    bool Close();
+    virtual bool Close();

 
     /**
         Close the current entry.
         It is called implicitly whenever another new entry is created with CopyEntry()
         or PutNextEntry(), or when the archive is closed.
     */
 
     /**
         Close the current entry.
         It is called implicitly whenever another new entry is created with CopyEntry()
         or PutNextEntry(), or when the archive is closed.
     */

-    bool CloseEntry();
+    virtual bool CloseEntry() = 0;

 
     /**
         Some archive formats have additional meta-data that applies to the archive
 
     /**
         Some archive formats have additional meta-data that applies to the archive


@@ -109,11 +111,11 @@ public:
         in which case the two streams set up a link and transfer the data
         when it becomes available.
     */
         in which case the two streams set up a link and transfer the data
         when it becomes available.
     */

-    bool CopyArchiveMetaData(wxArchiveInputStream& stream);
+    virtual bool CopyArchiveMetaData(wxArchiveInputStream& stream) = 0;

 
     /**
         Takes ownership of @a entry and uses it to create a new entry in the
 
     /**
         Takes ownership of @a entry and uses it to create a new entry in the

-        archive. @a entry is then opened in the input stream @e stream
+        archive. @a entry is then opened in the input stream @a stream

         and its contents copied to this stream.
 
         For archive types which compress entry data, CopyEntry() is likely to be
         and its contents copied to this stream.
 
         For archive types which compress entry data, CopyEntry() is likely to be


@@ -122,10 +124,10 @@ public:
 
         @a entry must be from the same archive file that @a stream is
         accessing. For non-seekable streams, @a entry must also be the last
 
         @a entry must be from the same archive file that @a stream is
         accessing. For non-seekable streams, @a entry must also be the last

-        thing read from @e stream.
+        thing read from @a stream.

     */
     */

-    bool CopyEntry(wxArchiveEntry* entry,
-                   wxArchiveInputStream& stream);
+    virtual bool CopyEntry(wxArchiveEntry* entry,
+                           wxArchiveInputStream& stream) = 0;

 
     /**
         Create a new directory entry (see wxArchiveEntry::IsDir) with the given
 
     /**
         Create a new directory entry (see wxArchiveEntry::IsDir) with the given


@@ -134,20 +136,22 @@ public:
         PutNextEntry() can also be used to create directory entries, by supplying
         a name with a trailing path separator.
     */
         PutNextEntry() can also be used to create directory entries, by supplying
         a name with a trailing path separator.
     */

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

 
     /**
         Takes ownership of entry and uses it to create a new entry in the archive.
         The entry's data can then be written by writing to this wxArchiveOutputStream.
     */
 
     /**
         Takes ownership of entry and uses it to create a new entry in the archive.
         The entry's data can then be written by writing to this wxArchiveOutputStream.
     */

-    bool PutNextEntry(wxArchiveEntry* entry);
+    virtual bool PutNextEntry(wxArchiveEntry* entry) = 0;

 
     /**
         Create a new entry with the given name, timestamp and size. The entry's
         data can then be written by writing to this wxArchiveOutputStream.
     */
 
     /**
         Create a new entry with the given name, timestamp and size. The entry's
         data can then be written by writing to this wxArchiveOutputStream.
     */

-    bool PutNextEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now(),
-                      off_t size = wxInvalidOffset);
+    virtual bool PutNextEntry(const wxString& name,
+                              const wxDateTime& dt = wxDateTime::Now(),
+                              wxFileOffset size = wxInvalidOffset) = 0;

 };
 
 
 };
 
 


@@ -156,14 +160,15 @@ public:
     @class wxArchiveEntry
     @wxheader{archive.h}
 
     @class wxArchiveEntry
     @wxheader{archive.h}
 

-    An abstract base class which serves as a common interface to
+    This is an abstract base class which serves as a common interface to

     archive entry classes such as wxZipEntry.
     These hold the meta-data (filename, timestamp, etc.), for entries
     in archive files such as zips and tars.
 
     archive entry classes such as wxZipEntry.
     These hold the meta-data (filename, timestamp, etc.), for entries
     in archive files such as zips and tars.
 

-    <b>About non-seekable streams</b>: this information applies only when reading
-    archives from non-seekable streams. When the stream is seekable GetNextEntry()
-    returns a fully populated wxArchiveEntry.
+    @section wxarchiveentry_nonseekable About non-seekable streams
+
+    This information applies only when reading archives from non-seekable streams.
+    When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry.

     See @ref overview_archive_noseek for more information.
 
     For generic programming, when the worst case must be assumed, you can rely on
     See @ref overview_archive_noseek for more information.
 
     For generic programming, when the worst case must be assumed, you can rely on


@@ -192,12 +197,12 @@ public:
     /**
         Gets the entry's timestamp.
     */
     /**
         Gets the entry's timestamp.
     */

-    wxDateTime GetDateTime();
+    virtual wxDateTime GetDateTime() const = 0;

 
     /**
         Sets the entry's timestamp.
     */
 
     /**
         Sets the entry's timestamp.
     */

-    const void SetDateTime(const wxDateTime& dt);
+    virtual void SetDateTime(const wxDateTime& dt) = 0;

 
     /**
         Returns the entry's name, by default in the native format.
 
     /**
         Returns the entry's name, by default in the native format.


@@ -206,7 +211,7 @@ public:
         If this is a directory entry, (i.e. if IsDir() is @true) then the
         returned string is the name with a trailing path separator.
     */
         If this is a directory entry, (i.e. if IsDir() is @true) then the
         returned string is the name with a trailing path separator.
     */

-    wxString GetName(wxPathFormat format = wxPATH_NATIVE);
+    virtual wxString GetName(wxPathFormat format = wxPATH_NATIVE) const = 0;

 
     /**
         Sets the entry's name.
 
     /**
         Sets the entry's name.


@@ -214,24 +219,24 @@ public:
 
         @see GetName()
     */
 
         @see GetName()
     */

-    const void SetName(const wxString& name,
-                       wxPathFormat format = wxPATH_NATIVE);
+    virtual void SetName(const wxString& name,
+                         wxPathFormat format = wxPATH_NATIVE) = 0;

 
     /**
         Returns the size of the entry's data in bytes.
     */
 
     /**
         Returns the size of the entry's data in bytes.
     */

-    off_t GetSize();
+    virtual wxFileOffset GetSize() const = 0;

 
     /**
         Sets the size of the entry's data in bytes.
     */
 
     /**
         Sets the size of the entry's data in bytes.
     */

-    const void SetSize(off_t size);
+    virtual void SetSize(wxFileOffset size) = 0;

 
     /**
         Returns the path format used internally within the archive to store
         filenames.
     */
 
     /**
         Returns the path format used internally within the archive to store
         filenames.
     */

-    wxPathFormat GetInternalFormat() const;
+    virtual wxPathFormat GetInternalFormat() const = 0;

 
     /**
         Returns the entry's filename in the internal format used within the
 
     /**
         Returns the entry's filename in the internal format used within the


@@ -240,15 +245,15 @@ public:
 
         The names of directory entries are returned without any trailing path
         separator. This gives a canonical name that can be used in comparisons.
 
         The names of directory entries are returned without any trailing path
         separator. This gives a canonical name that can be used in comparisons.

-        
+

         @see @ref overview_archive_byname
     */
         @see @ref overview_archive_byname
     */

-    wxString GetInternalName() const;
+    virtual wxString GetInternalName() const = 0;

 
     /**
         Returns a numeric value unique to the entry within the archive.
     */
 
     /**
         Returns a numeric value unique to the entry within the archive.
     */

-    off_t GetOffset() const;
+    virtual wxFileOffset GetOffset() const = 0;

 
     /**
         Returns @true if this is a directory entry.
 
     /**
         Returns @true if this is a directory entry.


@@ -262,22 +267,22 @@ public:
         unarchivers typically create whatever directories are necessary as they
         restore files, even if the archive contains no explicit directory entries.
     */
         unarchivers typically create whatever directories are necessary as they
         restore files, even if the archive contains no explicit directory entries.
     */

-    bool IsDir();
+    virtual bool IsDir() const = 0;

 
     /**
         Marks this entry as a directory if @a isDir is @true. See IsDir() for more info.
     */
 
     /**
         Marks this entry as a directory if @a isDir is @true. See IsDir() for more info.
     */

-    const void SetIsDir(bool isDir = true);
+    virtual void SetIsDir(bool isDir = true) = 0;

 
     /**
         Returns @true if the entry is a read-only file.
     */
 
     /**
         Returns @true if the entry is a read-only file.
     */

-    bool IsReadOnly();
+    virtual bool IsReadOnly() const = 0;

 
     /**
         Sets this entry as a read-only file.
     */
 
     /**
         Sets this entry as a read-only file.
     */

-    const void SetIsReadOnly(bool isReadOnly = true);
+    virtual void SetIsReadOnly(bool isReadOnly = true) = 0;

 
     /**
         Sets the notifier (see wxArchiveNotifier) for this entry.
 
     /**
         Sets the notifier (see wxArchiveNotifier) for this entry.


@@ -294,7 +299,7 @@ public:
     /**
         Unsets the notifier eventually attached to this entry.
     */
     /**
         Unsets the notifier eventually attached to this entry.
     */

-    void UnsetNotifier();
+    virtual void UnsetNotifier();

 };
 
 
 };
 
 


@@ -327,7 +332,7 @@ enum wxStreamProtocolType
     wxArchiveClassFactory::Find can also search for a factory by MIME type
     or wxFileSystem protocol.
 
     wxArchiveClassFactory::Find can also search for a factory by MIME type
     or wxFileSystem protocol.
 

-    The available factories can be enumerated using 
+    The available factories can be enumerated using

     wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
 
     @library{wxbase}
     wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
 
     @library{wxbase}


@@ -381,13 +386,13 @@ public:
         @code
         wxString list;
         const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
         @code
         wxString list;
         const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();

-    
+

         while (factory) {
             list << factory->GetProtocol() << _T("\n");
             factory = factory->GetNext();
         }
         @endcode
         while (factory) {
             list << factory->GetProtocol() << _T("\n");
             factory = factory->GetNext();
         }
         @endcode

-        
+

         GetFirst() and GetNext() return a pointer to a factory or @NULL if no more
         are available. They do not give away ownership of the factory.
     */
         GetFirst() and GetNext() return a pointer to a factory or @NULL if no more
         are available. They do not give away ownership of the factory.
     */


@@ -418,7 +423,7 @@ public:
         @code
         wxString list;
         const wxChar *const *p;
         @code
         wxString list;
         const wxChar *const *p;

-        
+

         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
             list << *p << _T("\n");
         @encode
         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
             list << *p << _T("\n");
         @encode


@@ -529,7 +534,7 @@ public:
 
     The first template parameter should be the type of archive input stream
     (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry
 
     The first template parameter should be the type of archive input stream
     (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry

-    (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString, 
+    (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString,

     wxArchiveEntry*).
 
     The @c wx/archive.h header defines the following typedefs:
     wxArchiveEntry*).
 
     The @c wx/archive.h header defines the following typedefs:


@@ -612,7 +617,7 @@ public:
 
     /**
         Construct the iterator that returns all the entries in the archive input
 
     /**
         Construct the iterator that returns all the entries in the archive input

-        stream @e arc.
+        stream @a arc.

     */
     wxArchiveIterator(Arc& arc);
 
     */
     wxArchiveIterator(Arc& arc);