Fix text origin and bounding box computations in wxSVGFileDC.

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

diff --git a/interface/wx/tarstrm.h b/interface/wx/tarstrm.h
index 3eea841ecbb1bd138a54dbfa0f46a3c37e5684f1..2381dfd888b3e61bb909c15a21e3c7edb17b2648 100644 (file)
--- a/interface/wx/tarstrm.h
+++ b/interface/wx/tarstrm.h
@@ -1,31 +1,55 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        tarstrm.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        tarstrm.h

-// Purpose:     interface of wxTarInputStream
+// Purpose:     interface of wxTar* classes

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+
+/** wxTarEntry::GetTypeFlag() values */
+enum wxTarType
+{
+    wxTAR_REGTYPE   = '0',      //!< regular file
+    wxTAR_LNKTYPE   = '1',      //!< hard link
+    wxTAR_SYMTYPE   = '2',      //!< symbolic link
+    wxTAR_CHRTYPE   = '3',      //!< character special
+    wxTAR_BLKTYPE   = '4',      //!< block special
+    wxTAR_DIRTYPE   = '5',      //!< directory
+    wxTAR_FIFOTYPE  = '6',      //!< named pipe
+    wxTAR_CONTTYPE  = '7'       //!< contiguous file
+};
+
+/** Archive Formats (use wxTAR_PAX, it's backward compatible) used by wxTarEntry */
+enum wxTarFormat
+{
+    wxTAR_USTAR,                //!< POSIX.1-1990 tar format
+    wxTAR_PAX                   //!< POSIX.1-2001 tar format
+};
+
+

 /**
     @class wxTarInputStream
 
     Input stream for reading tar files.
 
 /**
     @class wxTarInputStream
 
     Input stream for reading tar files.
 

-    wxTarInputStream::GetNextEntry returns an
-     wxTarEntry object containing the meta-data
-    for the next entry in the tar (and gives away ownership). Reading from
-    the wxTarInputStream 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().
+    wxTarInputStream::GetNextEntry() returns a wxTarEntry object containing the
+    meta-data for the next entry in the tar (and gives away ownership).
+    Reading from the wxTarInputStream then returns the entry's data.
+    wxTarInputStream::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, wxTarInputStream::GetNextEntry() returns @NULL
+    and sets wxTarInputStream::Eof().

 
     Tar entries are seekable if the parent stream is seekable. In practice this
     usually means they are only seekable if the tar is stored as a local file and
     is not compressed.
 
     @library{wxbase}
 
     Tar entries are seekable if the parent stream is seekable. In practice this
     usually means they are only seekable if the tar is stored as a local file and
     is not compressed.
 
     @library{wxbase}

-    @category{streams}
+    @category{archive,streams}

 
 

-    @see @ref overview_wxarcbyname "Looking up an archive entry by name"
+    @see @ref overview_archive_byname

 */
 class wxTarInputStream : public wxArchiveInputStream
 {
 */
 class wxTarInputStream : public wxArchiveInputStream
 {


@@ -33,9 +57,11 @@ public:
     //@{
     /**
         Constructor. In a Unicode build the second parameter @a conv is
     //@{
     /**
         Constructor. In a Unicode build the second parameter @a conv is

-        used to translate fields from the standard tar header into Unicode. It has
-        no effect on the stream's data. @a conv is only used for the standard
+        used to translate fields from the standard tar header into Unicode.
+
+        It has no effect on the stream's data. @a conv is only used for the standard

         tar headers, any pax extended headers are always UTF-8 encoded.
         tar headers, any pax extended headers are always UTF-8 encoded.

+

         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.
     */


@@ -46,23 +72,24 @@ 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();
 
     /**
         Closes the current entry if one is open, then reads the meta-data for
     */
     bool CloseEntry();
 
     /**
         Closes the current entry if one is open, then reads the meta-data for

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

     */
     wxTarEntry* GetNextEntry();
 
     /**
         Closes the current entry if one is open, then opens the entry specified
         by the @a entry object.
     */
     wxTarEntry* GetNextEntry();
 
     /**
         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 tar file, and the tar should
-        be on a seekable stream.
+
+        @a entry should be from the same tar file, and the tar should be on a
+        seekable stream.

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


@@ -72,14 +99,14 @@ public:
 /**
     @class wxTarClassFactory
 
 /**
     @class wxTarClassFactory
 

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

 
     @library{wxbase}
 
     @library{wxbase}

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

 
 

-    @see @ref overview_wxarc "Archive formats such as zip", @ref
-    overview_wxarcgeneric "Generic archive programming", wxTarEntry, wxTarInputStream, wxTarOutputStream
+    @see @ref overview_archive, @ref overview_archive_generic,
+         wxTarEntry, wxTarInputStream, wxTarOutputStream

 */
 class wxTarClassFactory : public wxArchiveClassFactory
 {
 */
 class wxTarClassFactory : public wxArchiveClassFactory
 {


@@ -94,16 +121,15 @@ public:
 
     Output stream for writing tar files.
 
 
     Output stream for writing tar files.
 

-    wxTarOutputStream::PutNextEntry is used to create
-    a new entry in the output tar, then the entry's data is written to the
-    wxTarOutputStream. Another call to PutNextEntry() closes the current
-    entry and begins the next.
+    wxTarOutputStream::PutNextEntry() is used to create a new entry in the output tar,
+    then the entry's data is written to the wxTarOutputStream.
+    Another call to wxTarOutputStream::PutNextEntry() closes the current entry
+    and begins the next.

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

-    @see @ref overview_wxarc "Archive formats such as zip", wxTarEntry,
-    wxTarInputStream
+    @see @ref overview_archive, wxTarEntry, wxTarInputStream

 */
 class wxTarOutputStream : public wxArchiveOutputStream
 {
 */
 class wxTarOutputStream : public wxArchiveOutputStream
 {


@@ -112,18 +138,21 @@ 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.

+

         In a Unicode build the third parameter @a conv is used to translate the
         headers fields into 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
         headers fields into an 8-bit encoding. It has no effect on the stream's data.

+

         When the @a format is @e wxTAR_PAX, pax extended headers are generated
         when any header field will not fit the standard tar header block or if it
         uses any non-ascii characters.
         When the @a format is @e wxTAR_PAX, pax extended headers are generated
         when any header field will not fit the standard tar header block or if it
         uses any non-ascii characters.

+

         Extended headers are stored as extra 'files' within the tar, and will be
         extracted as such by any other tar program that does not understand them.
         The @a conv parameter only affect the standard tar headers, the extended
         headers are always UTF-8 encoded.
         Extended headers are stored as extra 'files' within the tar, and will be
         extracted as such by any other tar program that does not understand them.
         The @a conv parameter only affect the standard tar headers, the extended
         headers are always UTF-8 encoded.

-        When the @a format is @e wxTAR_USTAR, no extended headers are
-        generated, and instead a warning message is logged if any header field
-        overflows.
+
+        When the @a format is @e wxTAR_USTAR, no extended headers are generated,
+        and instead a warning message is logged if any header field overflows.

     */
     wxTarOutputStream(wxOutputStream& stream,
                       wxTarFormat format = wxTAR_PAX,
     */
     wxTarOutputStream(wxOutputStream& stream,
                       wxTarFormat format = wxTAR_PAX,


@@ -134,10 +163,10 @@ public:
     //@}
 
     /**
     //@}
 
     /**

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

     */
     */

-    ~wxTarOutputStream();
+    virtual ~wxTarOutputStream();

 
     /**
         Finishes writing the tar, returning @true if successful.
 
     /**
         Finishes writing the tar, returning @true if successful.


@@ -146,63 +175,64 @@ 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 tar is closed.
+        Close the current entry.
+
+        It is called implicitly whenever another new entry is created with
+        CopyEntry() or PutNextEntry(), or when the tar is closed.

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

-        See wxArchiveOutputStream::CopyArchiveMetaData.
+        See wxArchiveOutputStream::CopyArchiveMetaData().

         For the tar format this function does nothing.
     */
     bool CopyArchiveMetaData(wxTarInputStream& s);
 
     /**
         For the tar format this function does nothing.
     */
     bool CopyArchiveMetaData(wxTarInputStream& s);
 
     /**

-        Takes ownership of @a entry and uses it to create a new entry
-        in the tar. @a entry is then opened in @a inputStream and its contents
-        copied to this stream.
+        Takes ownership of @a entry and uses it to create a new entry in the tar.
+        @a entry is then opened in @a inputStream and its contents copied to this stream.
+

         For some other archive formats CopyEntry() is much more efficient than
         transferring the data using Read() and Write() since it will copy them
         For some other archive formats CopyEntry() is much more efficient than
         transferring the data using Read() and Write() since it will copy them

-        without decompressing and recompressing them. For tar however it makes
-        no difference.
+        without decompressing and recompressing them.
+        For tar however it makes no difference.
+

         For tars on seekable streams, @a entry must be from the same tar file
         For tars on seekable streams, @a entry must be from the same tar file

-        as @e stream. For non-seekable streams, @a entry must also be the
-        last thing read from @e inputStream.
+        as @a inputStream. For non-seekable streams, @a entry must also be the
+        last thing read from @a inputStream.

     */
     bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream);
 
     //@{
     /**
         The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes.
     */
     bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream);
 
     //@{
     /**
         The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes.

-        Defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
-        (see the @ref wxtaroutputstream() constructor), as
-        specified in the POSIX standards.
+
+        The blocking factor defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
+        (see wxTarOutputStream()), as specified in the POSIX standards.

     */
     */

-    int GetBlockingFactor();
-    const void SetBlockingFactor(int factor);
+    int GetBlockingFactor() const;
+    void SetBlockingFactor(int factor);

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

-        )
-        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 wxFileOffset@e size = wxInvalidOffset)
-        Create a new entry with the given name, timestamp and size.
+        Takes ownership of entry and uses it to create a new entry in the tar.

     */
     bool PutNextEntry(wxTarEntry* entry);
     */
     bool PutNextEntry(wxTarEntry* 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(),
+                      wxFileOffset size = wxInvalidOffset);

 };
 
 
 };
 
 


@@ -212,135 +242,161 @@ public:
 
     Holds the meta-data for an entry in a tar.
 
 
     Holds the meta-data for an entry in a tar.
 

+    @section tarentry_fields Field availability
+
+    The tar format stores all the meta-data for an entry ahead of its data,
+    therefore GetNextEntry() always returns a fully populated wxTarEntry object,
+    both when reading from seekable and non-seekable streams.
+

     @library{wxbase}
     @library{wxbase}

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

 
 

-    @see @ref overview_wxarc "Archive formats such as zip", wxTarInputStream,
-    wxTarOutputStream
+    @see @ref overview_archive, wxTarInputStream, wxTarOutputStream

 */
 class wxTarEntry : public wxArchiveEntry
 {
 public:
 */
 class wxTarEntry : public wxArchiveEntry
 {
 public:

-    //@{
+    /**
+        Constructor.
+
+        The tar archive format stores the entry's size ahead of the entry's data.
+        Therefore when creating an archive on a non-seekable stream it is necessary
+        to supply the correct size when each entry is created.
+    */
+    wxTarEntry(const wxString& name = wxEmptyString,
+               const wxDateTime& dt = wxDateTime::Now(),
+               wxFileOffset size = wxInvalidOffset);
+

     /**
         Copy constructor.
     */
     /**
         Copy constructor.
     */

-    wxTarEntry(const wxString& name = wxEmptyString);

     wxTarEntry(const wxTarEntry& entry);
     wxTarEntry(const wxTarEntry& entry);

-    //@}

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

-        The entry's access time stamp. See also
-         wxArchiveEntry::Get/SetDateTime.
+        Gets/sets the entry's access time stamp.
+        See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().

     */
     */

-    wxDateTime GetAccessTime();
-    const void SetAccessTime(const wxDateTime& dt);
+    wxDateTime GetAccessTime() const;
+    void SetAccessTime(const wxDateTime& dt);

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

-        The entry's creation time stamp. See also
-         wxArchiveEntry::Get/SetDateTime.
+        The entry's creation time stamp.
+        See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().

     */
     */

-    wxDateTime GetCreateTime();
-    const void SetCreateTime(const wxDateTime& dt);
+    wxDateTime GetCreateTime() const;
+    void SetCreateTime(const wxDateTime& dt);

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

-        OS specific IDs defining a device, these are only meaningful when
-         TypeFlag() is set to @e wxTAR_CHRTYPE
-         or @e wxTAR_BLKTYPE.
+        OS specific IDs defining a device; these are only meaningful when
+        wxTarEntry::GetTypeFlag() is @e wxTAR_CHRTYPE or @e wxTAR_BLKTYPE.

     */
     */

-    int GetDevMajor();
-    const int GetDevMinor();
-    const void SetDevMajor(int dev);
+    int GetDevMajor() const;
+    int GetDevMinor() const;
+    void SetDevMajor(int dev);

     void SetDevMinor(int dev);
     //@}
 
     //@{
     /**
     void SetDevMinor(int dev);
     //@}
 
     //@{
     /**

-        The user ID and group ID that has @ref mode() permissions over
-        this entry. These values aren't usually useful unless the file will only be
-        restored to the same system it originated from. @ref unamegname()
-        "Get/SetGroupName and
-        Get/SetUserName" can be used instead.
+        The user ID and group ID that has permissions (see wxTarEntry::GetMode())
+        over this entry.
+
+        These values aren't usually useful unless the file will only be
+        restored to the same system it originated from.
+        wxTarEntry::GetGroupName() and wxTarEntry::GetUserName() can be used instead.

     */
     */

-    int GetGroupId();
-    const int GetUserId();
-    const void SetGroupId(int id);
+    int GetGroupId() const;
+    int GetUserId() const;
+    void SetGroupId(int id);

     void SetUserId(int id);
     //@}
 
     //@{
     /**
     void SetUserId(int id);
     //@}
 
     //@{
     /**

-        The names of the user and group that has @ref mode() permissions
+        The names of the user and group that has permissions (see wxTarEntry::GetMode())

         over this entry. These are not present in very old tars.
     */
         over this entry. These are not present in very old tars.
     */

-    wxString GetGroupName();
-    const wxString  GetUserName();
-    const void SetGroupName(const wxString& group);
+    wxString GetGroupName() const;
+    wxString GetUserName() const;
+    void SetGroupName(const wxString& group);

     void SetUserName(const wxString& user);
     //@}
 
     //@{
     /**
         The filename of a previous entry in the tar that this entry is a link to.
     void SetUserName(const wxString& user);
     //@}
 
     //@{
     /**
         The filename of a previous entry in the tar that this entry is a link to.

-        Only meaningful when TypeFlag() is set
-        to @e wxTAR_LNKTYPE or @e wxTAR_SYMTYPE.
+        Only meaningful when wxTarEntry::GetTypeFlag() is set to @e wxTAR_LNKTYPE
+        or @e wxTAR_SYMTYPE.

     */
     */

-    wxString GetLinkName();
-    const void SetLinkName(const wxString& link);
+    wxString GetLinkName() const;
+    void SetLinkName(const wxString& link);

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

-        UNIX permission bits for this entry. Giving read, write and execute permissions
-        to the file's @ref unamegname() "User and Group" and to others.
-        Symbols are defined for them in wx/file.h.
+        UNIX permission bits for this entry.
+        Giving read, write and execute permissions to the file's user and group
+        (see GetGroupName() and GetUserName()) and to others.
+
+        The integer is one or more ::wxPosixPermissions flags OR-combined.

     */
     */

-    int GetMode();
-    const void SetMode(int mode);
+    int GetMode() const;
+    void SetMode(int mode);

     //@}
 
     //@{
     /**
         The size of the entry's data in bytes.
     //@}
 
     //@{
     /**
         The size of the entry's data in bytes.

+

         The tar archive format stores the entry's size ahead of the entry's data.
         Therefore when creating an archive on a non-seekable stream it is necessary to
         The tar archive format stores the entry's size ahead of the entry's data.
         Therefore when creating an archive on a non-seekable stream it is necessary to

-        supply the correct size when each entry is created. For seekable streams this
-        is not necessary as wxTarOutputStream will attempt
+        supply the correct size when each entry is created.
+
+        For seekable streams this is not necessary as wxTarOutputStream will attempt

         to seek back and fix the entry's header when the entry is closed, though it is
         still more efficient if the size is given beforehand.
     */
         to seek back and fix the entry's header when the entry is closed, though it is
         still more efficient if the size is given beforehand.
     */

-    void SetSize(wxFileOffset size) const;
+    void SetSize(wxFileOffset size);

     wxFileOffset GetSize() const;
     //@}
 
     //@{
     /**
     wxFileOffset GetSize() const;
     //@}
 
     //@{
     /**

-        Returns the type of the entry. It should be one of the following:
+        Returns/Sets the type of the entry as a ::wxTarType value.

 
 

-        When creating archives use just these values. When reading archives
-        any other values should be treated as @e wxTAR_REGTYPE.
+        When creating archives use only one of ::wxTarType values.
+        When reading archives, GetTypeFlag() may return a value which does not
+        match any value of ::wxTarType; in this case the returned value should be
+        treated as @e wxTAR_REGTYPE.

     */
     */

-    int GetTypeFlag();
-    const void SetTypeFlag(int type);
+    int GetTypeFlag() const;
+    void SetTypeFlag(int type);

     //@}
 
     //@}
 

-    //@{
+    /**
+        Returns the entry's filename in the internal format used within the archive.
+
+        The name can include directory components, i.e. it can be a full path.
+        The names of directory entries are returned without any trailing path separator.
+        This gives a canonical name that can be used in comparisons.
+    */
+    wxString GetInternalName() const;
+

     /**
         A static member that translates a filename into the internal format used
     /**
         A static member that translates a filename into the internal format used

-        within the archive. If the third parameter is provided, the bool pointed
-        to is set to indicate whether the name looks like a directory name
-        (i.e. has a trailing path separator).
+        within the archive.
+
+        If the third parameter is provided, the bool pointed to is set to indicate
+        whether the name looks like a directory name (i.e. has a trailing path separator).

     */
     */

-    wxString GetInternalName();
-    const wxString  GetInternalName(const wxString& name,
+    static wxString GetInternalName(const wxString& name,

                                     wxPathFormat format = wxPATH_NATIVE,
                                     bool* pIsDir = NULL);
                                     wxPathFormat format = wxPATH_NATIVE,
                                     bool* pIsDir = NULL);

-    //@}

 
     /**
         Assignment operator.
 
     /**
         Assignment operator.