Update archive overview for class factory changes.

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

diff --git a/docs/latex/wx/arc.tex b/docs/latex/wx/arc.tex
index a5ac17d7e3b6e8cb0b40e86681d23b346c351fb4..56a76abaa92e1bfad1b913396c6ab5834b6d039e 100644 (file)
--- a/docs/latex/wx/arc.tex
+++ b/docs/latex/wx/arc.tex
@@ -10,8 +10,7 @@
 \section{Archive formats such as zip}\label{wxarc}
 
 The archive classes handle archive formats such as zip, tar, rar and cab.
 \section{Archive formats such as zip}\label{wxarc}
 
 The archive classes handle archive formats such as zip, tar, rar and cab.

-Currently only the wxZip classes are included. wxTar classes are under
-development at \urlref{wxCode}{http://wxcode.sf.net}.
+Currently wxZip and wxTar classes are included.

 
 For each archive type, there are the following classes (using zip here
 as an example):
 
 For each archive type, there are the following classes (using zip here
 as an example):


@@ -79,8 +78,7 @@ the end of the entry's data.
 When there are no more entries, GetNextEntry() returns NULL and sets Eof().
 
 \begin{verbatim}
 When there are no more entries, GetNextEntry() returns NULL and sets Eof().
 
 \begin{verbatim}

-    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
-    wxZipEntryPtr entry;
+    auto_ptr<wxZipEntry> entry;

 
     wxFFileInputStream in(_T("test.zip"));
     wxZipInputStream zip(in);
 
     wxFFileInputStream in(_T("test.zip"));
     wxZipInputStream zip(in);


@@ -94,15 +92,6 @@ When there are no more entries, GetNextEntry() returns NULL and sets Eof().
 
 \end{verbatim}
 
 
 \end{verbatim}
 

-The \helpref{smart pointer}{wxscopedptr} type {\em wxZipEntryPtr}
-can be created like this:
-
-\begin{verbatim}
-    #include <wx/ptr_scpd.h>
-    wxDEFINE_SCOPED_PTR_TYPE(wxZipEntry);
-
-\end{verbatim}
-

 
 \subsection{Modifying an archive}\label{wxarcmodify}
 
 
 \subsection{Modifying an archive}\label{wxarcmodify}
 


@@ -125,14 +114,13 @@ be helpful to do this.
 For example to delete all entries matching the pattern "*.txt":
 
 \begin{verbatim}
 For example to delete all entries matching the pattern "*.txt":
 
 \begin{verbatim}

-    wxFFileInputStreamPtr in(new wxFFileInputStream(_T("test.zip")));
+    auto_ptr<wxFFileInputStream> in(new wxFFileInputStream(_T("test.zip")));

     wxTempFileOutputStream out(_T("test.zip"));
 
     wxZipInputStream inzip(*in);
     wxZipOutputStream outzip(out);
 
     wxTempFileOutputStream out(_T("test.zip"));
 
     wxZipInputStream inzip(*in);
     wxZipOutputStream outzip(out);
 

-    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
-    wxZipEntryPtr entry;
+    auto_ptr<wxZipEntry> entry;

 
     // transfer any meta-data for the archive as a whole (the zip comment
     // in the case of zip)
 
     // transfer any meta-data for the archive as a whole (the zip comment
     // in the case of zip)


@@ -153,16 +141,6 @@ For example to delete all entries matching the pattern "*.txt":
 
 \end{verbatim}
 
 
 \end{verbatim}
 

-The \helpref{smart pointer}{wxscopedptr} types {\em wxZipEntryPtr}
-and {\em wxFFileInputStreamPtr} can be created like this:
-
-\begin{verbatim}
-    #include <wx/ptr_scpd.h>
-    wxDEFINE_SCOPED_PTR_TYPE(wxZipEntry);
-    wxDEFINE_SCOPED_PTR_TYPE(wxFFileInputStream);
-
-\end{verbatim}
-

 
 \subsection{Looking up an archive entry by name}\label{wxarcbyname}
 
 
 \subsection{Looking up an archive entry by name}\label{wxarcbyname}
 


@@ -191,8 +169,7 @@ it is better to convert the local name to the archive's internal format
 and search for that:
 
 \begin{verbatim}
 and search for that:
 
 \begin{verbatim}

-    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
-    wxZipEntryPtr entry;
+    auto_ptr<wxZipEntry> entry;

 
     // convert the local name we are looking for into the internal format
     wxString name = wxZipEntry::GetInternalName(localname);
 
     // convert the local name we are looking for into the internal format
     wxString name = wxZipEntry::GetInternalName(localname);


@@ -279,8 +256,8 @@ entry (e.g. filename)}
 
 In order to able to write generic code it's necessary to be able to create
 instances of the classes without knowing which archive type is being used.
 
 In order to able to write generic code it's necessary to be able to create
 instances of the classes without knowing which archive type is being used.

-So there is a class factory for each archive type, derived from
- \helpref{wxArchiveClassFactory}{wxarchiveclassfactory}, which can create
+To allow this there is a class factory for each archive type, derived from
+ \helpref{wxArchiveClassFactory}{wxarchiveclassfactory}, that can create

 the other classes.
 
 For example, given {\it wxArchiveClassFactory* factory}, streams and
 the other classes.
 
 For example, given {\it wxArchiveClassFactory* factory}, streams and


@@ -288,52 +265,68 @@ entries can be created like this:
 
 \begin{verbatim}
     // create streams without knowing their type
 
 \begin{verbatim}
     // create streams without knowing their type

-    wxArchiveInputStreamPtr  inarc(factory->NewStream(in));
-    wxArchiveOutputStreamPtr outarc(factory->NewStream(out));
+    auto_ptr<wxArchiveInputStream> inarc(factory->NewStream(in));
+    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));

 
     // create an empty entry object
 
     // create an empty entry object

-    wxArchiveEntryPtr        entry(factory->NewEntry());
+    auto_ptr<wxArchiveEntry> entry(factory->NewEntry());

 
 \end{verbatim}
 
 
 \end{verbatim}
 

-The \helpref{smart pointer}{wxscopedptr} types {\em wxArchiveInputStreamPtr},
-{\em wxArchiveOutputStreamPtr} and {\em wxArchiveEntryPtr} would need to
-have already have been defined, which could be done like this:
+For the factory itself, the static member
+ \helpref{wxArchiveClassFactory::Find()}{wxarchiveclassfactoryfind}.
+can be used to find a class factory that can handle a given file
+extension or mime type. For example, given {\it filename}:

 
 \begin{verbatim}
 
 \begin{verbatim}

-    #include <wx/ptr_scpd.h>
-    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveInputStream);
-    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveOutputStream);
-    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveEntry);
+    const wxArchiveClassFactory *factory;
+    factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
+
+    if (factory)
+        stream = factory->NewStream(new wxFFileInputStream(filename));

 
 \end{verbatim}
 
 
 \end{verbatim}
 

-The class factory itself can either be created explicitly:
+{\it Find} does not give away ownership of the returned pointer, so it
+does not need to be deleted.

 
 

-\begin{verbatim}
-    wxArchiveClassFactory *factory = new wxZipClassFactory;
-
-\end{verbatim}
+There are similar class factories for the filter streams that handle the
+compression and decompression of a single stream, such as wxGzipInputStream.
+These can be found using
+ \helpref{wxFilterClassFactory::Find()}{wxfilterclassfactoryfind}.

 
 

-or using wxWidgets' \helpref{RTTI}{runtimeclassoverview}:
+For example, to list the contents of archive {\it filename}:

 
 \begin{verbatim}
 
 \begin{verbatim}

-wxArchiveClassFactory *MakeFactory(const wxString& type)
-{
-    wxString name = _T("wx") + type.Left(1).Upper() +
-                    type.Mid(1).Lower() + _T("ClassFactory");
-
-    wxObject *pObj = wxCreateDynamicObject(name);
-    wxArchiveClassFactory *pcf = wxDynamicCast(pObj, wxArchiveClassFactory);
+    auto_ptr<wxInputStream> in(new wxFFileInputStream(filename));

 
 

-    if (!pcf) {
-        wxLogError(_T("can't handle '%s' archives"), type.c_str());
-        delete pObj;
+    if (in->IsOk())
+    {
+        // look for a filter handler, e.g. for '.gz'
+        const wxFilterClassFactory *fcf;
+        fcf = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
+        if (fcf) {
+            in.reset(fcf->NewStream(in.release()));
+            // pop the extension, so if it was '.tar.gz' it is now just '.tar'
+            filename = fcf->PopExtension(filename);
+        }
+
+        // look for a archive handler, e.g. for '.zip' or '.tar'
+        const wxArchiveClassFactory *acf;
+        acf = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
+        if (acf) {
+            auto_ptr<wxArchiveInputStream> arc(acf->NewStream(in.release()));
+            auto_ptr<wxArchiveEntry> entry;
+
+            // list the contents of the archive
+            while ((entry.reset(arc->GetNextEntry())), entry.get() != NULL)
+                std::wcout << entry->GetName().c_str() << "\n";
+        }
+        else {
+            wxLogError(_T("can't handle '%s'"), filename.c_str());
+        }

     }
 
     }
 

-    return pcf;
-}
-

 \end{verbatim}
 
 
 \end{verbatim}
 
 


@@ -414,9 +407,9 @@ required field before writing it with
  \helpref{CopyEntry()}{wxarchiveoutputstreamcopyentry}:
 
 \begin{verbatim}
  \helpref{CopyEntry()}{wxarchiveoutputstreamcopyentry}:
 
 \begin{verbatim}

-    wxArchiveInputStreamPtr  arc(factory->NewStream(in));
-    wxArchiveOutputStreamPtr outarc(factory->NewStream(out));
-    wxArchiveEntryPtr        entry;
+    auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
+    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
+    auto_ptr<wxArchiveEntry> entry;

 
     outarc->CopyArchiveMetaData(*arc);
 
 
     outarc->CopyArchiveMetaData(*arc);
 


@@ -452,10 +445,10 @@ then \helpref{SetNotifier()}{wxarchiveentrynotifier} is called before
 CopyEntry():
 
 \begin{verbatim}
 CopyEntry():
 
 \begin{verbatim}

-    wxArchiveInputStreamPtr  arc(factory->NewStream(in));
-    wxArchiveOutputStreamPtr outarc(factory->NewStream(out));
-    wxArchiveEntryPtr        entry;
-    MyNotifier               notifier;
+    auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
+    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
+    auto_ptr<wxArchiveEntry> entry;
+    MyNotifier notifier;

 
     outarc->CopyArchiveMetaData(*arc);
 
 
     outarc->CopyArchiveMetaData(*arc);
 

diff --git a/docs/latex/wx/zipstrm.tex b/docs/latex/wx/zipstrm.tex
index b7cbc612bee2a31cdd9d877b829eb223d5055b6a..bf8b8e93e5061d4411b0baf9bde6a24749f72918 100644 (file)
--- a/docs/latex/wx/zipstrm.tex
+++ b/docs/latex/wx/zipstrm.tex
@@ -19,7 +19,7 @@ for details.
 \wxheading{See also}
 
 \helpref{Archive formats such as zip}{wxarc}\\
 \wxheading{See also}
 
 \helpref{Archive formats such as zip}{wxarc}\\

-\helpref{Generic archive programming}{wxarcgeneric}
+\helpref{Generic archive programming}{wxarcgeneric}\\

 \helpref{wxZipEntry}{wxzipentry}\\
 \helpref{wxZipInputStream}{wxzipinputstream}\\
 \helpref{wxZipOutputStream}{wxzipoutputstream}
 \helpref{wxZipEntry}{wxzipentry}\\
 \helpref{wxZipInputStream}{wxzipinputstream}\\
 \helpref{wxZipOutputStream}{wxzipoutputstream}