Update archive overview for class factory changes.

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

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.
-Currently only the wxZip classes are included. wxTar classes are under
+Currently wxZip and wxTar classes are included.
-development at \urlref{wxCode}{http://wxcode.sf.net}.
 
 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}
-    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
+    auto_ptr<wxZipEntry> entry;
-    wxZipEntryPtr entry;
 
     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}
 
-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}
 
@@ -125,14 +114,13 @@ be helpful to do this.
 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);
 
-    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
+    auto_ptr<wxZipEntry> entry;
-    wxZipEntryPtr entry;
 
     // 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}
 
-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}
 
@@ -191,8 +169,7 @@ it is better to convert the local name to the archive's internal format
 and search for that:
 
 \begin{verbatim}
-    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
+    auto_ptr<wxZipEntry> entry;
-    wxZipEntryPtr entry;
 
     // 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.
-So there is a class factory for each archive type, derived from
+To allow this there is a class factory for each archive type, derived from
- \helpref{wxArchiveClassFactory}{wxarchiveclassfactory}, which can create
+ \helpref{wxArchiveClassFactory}{wxarchiveclassfactory}, that can create
 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
-    wxArchiveInputStreamPtr  inarc(factory->NewStream(in));
+    auto_ptr<wxArchiveInputStream> inarc(factory->NewStream(in));
-    wxArchiveOutputStreamPtr outarc(factory->NewStream(out));
+    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
 
     // create an empty entry object
-    wxArchiveEntryPtr        entry(factory->NewEntry());
+    auto_ptr<wxArchiveEntry> entry(factory->NewEntry());
 
 \end{verbatim}
 
-The \helpref{smart pointer}{wxscopedptr} types {\em wxArchiveInputStreamPtr},
+For the factory itself, the static member
-{\em wxArchiveOutputStreamPtr} and {\em wxArchiveEntryPtr} would need to
+ \helpref{wxArchiveClassFactory::Find()}{wxarchiveclassfactoryfind}.
-have already have been defined, which could be done like this:
+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}
-    #include <wx/ptr_scpd.h>
+    const wxArchiveClassFactory *factory;
-    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveInputStream);
+    factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
-    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveOutputStream);
+
-    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveEntry);
+    if (factory)
+        stream = factory->NewStream(new wxFFileInputStream(filename));
 
 \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.
+
+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}.
+
+For example, to list the contents of archive {\it filename}:
 
 \begin{verbatim}
-    wxArchiveClassFactory *factory = new wxZipClassFactory;
+    auto_ptr<wxInputStream> in(new wxFFileInputStream(filename));
 
-\end{verbatim}
+    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);
+        }
 
-or using wxWidgets' \helpref{RTTI}{runtimeclassoverview}:
+        // 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;
 
-\begin{verbatim}
+            // list the contents of the archive
-wxArchiveClassFactory *MakeFactory(const wxString& type)
+            while ((entry.reset(arc->GetNextEntry())), entry.get() != NULL)
-{
+                std::wcout << entry->GetName().c_str() << "\n";
-    wxString name = _T("wx") + type.Left(1).Upper() +
+        }
-                    type.Mid(1).Lower() + _T("ClassFactory");
+        else {
-
+            wxLogError(_T("can't handle '%s'"), filename.c_str());
-    wxObject *pObj = wxCreateDynamicObject(name);
+        }
-    wxArchiveClassFactory *pcf = wxDynamicCast(pObj, wxArchiveClassFactory);
-
-    if (!pcf) {
-        wxLogError(_T("can't handle '%s' archives"), type.c_str());
-        delete pObj;
     }
 
-    return pcf;
-}
-
 \end{verbatim}
 
 
@@ -414,9 +407,9 @@ required field before writing it with
  \helpref{CopyEntry()}{wxarchiveoutputstreamcopyentry}:
 
 \begin{verbatim}
-    wxArchiveInputStreamPtr  arc(factory->NewStream(in));
+    auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
-    wxArchiveOutputStreamPtr outarc(factory->NewStream(out));
+    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
-    wxArchiveEntryPtr        entry;
+    auto_ptr<wxArchiveEntry> entry;
 
     outarc->CopyArchiveMetaData(*arc);
 
@@ -452,10 +445,10 @@ then \helpref{SetNotifier()}{wxarchiveentrynotifier} is called before
 CopyEntry():
 
 \begin{verbatim}
-    wxArchiveInputStreamPtr  arc(factory->NewStream(in));
+    auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
-    wxArchiveOutputStreamPtr outarc(factory->NewStream(out));
+    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
-    wxArchiveEntryPtr        entry;
+    auto_ptr<wxArchiveEntry> entry;
-    MyNotifier               notifier;
+    MyNotifier notifier;
 
     outarc->CopyArchiveMetaData(*arc);
 

docs/latex/wx/zipstrm.tex

@@ -19,7 +19,7 @@ for details.
 \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}