From 716b1f7091622187312a86257eac0570d0ccd8a2 Mon Sep 17 00:00:00 2001
From: Michael Wetherell <mike.wetherell@ntlworld.com>
Date: Sun, 29 Oct 2006 12:56:48 +0000
Subject: [PATCH] Document filter streams take owner ship when created with a
 pointer, new feature of the archive factories and new filter factories.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@42614 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/archive.tex    | 156 +++++++++++++++++++++++++++--
 docs/latex/wx/classes.tex    |   1 +
 docs/latex/wx/fltfactory.tex | 186 +++++++++++++++++++++++++++++++++++
 docs/latex/wx/fltinstr.tex   |  10 ++
 docs/latex/wx/fltoutst.tex   |  10 ++
 docs/latex/wx/strmzlib.tex   |  10 ++
 docs/latex/wx/zipstrm.tex    |  12 ++-
 7 files changed, 374 insertions(+), 11 deletions(-)
 create mode 100644 docs/latex/wx/fltfactory.tex

diff --git a/docs/latex/wx/archive.tex b/docs/latex/wx/archive.tex
index 15dd1c64df..770071328a 100644
--- a/docs/latex/wx/archive.tex
+++ b/docs/latex/wx/archive.tex
@@ -5,13 +5,23 @@
 
 \section{\class{wxArchiveClassFactory}}\label{wxarchiveclassfactory}
 
-An abstract base class which serves as a common interface to
-archive class factories such as \helpref{wxZipClassFactory}{wxzipclassfactory}.
+Allows the creation of streams to handle archive formats such
+as zip and tar.
+
+For example, given a filename you can search for a factory that will
+handle it and create a stream to read it:
 
-For each supported archive type (such as zip) there is a class factory
-derived from wxArchiveClassFactory, which allows archive objects to be
-created in a generic way, without knowing the particular type of archive
-being used.
+\begin{verbatim}
+    factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
+    if (factory)
+        stream = factory->NewStream(new wxFFileInputStream(filename));
+
+\end{verbatim}
+
+\helpref{Find()}{wxarchiveclassfactoryfind} can also search
+for a factory by MIME type or wxFileSystem protocol.
+The available factories can be enumerated
+using \helpref{GetFirst() and GetNext()}{wxarchiveclassfactorygetfirst}.
 
 \wxheading{Derived from}
 
@@ -21,13 +31,27 @@ being used.
 
 <wx/archive.h>
 
+\wxheading{Data structures}
+
+\begin{verbatim}
+enum wxStreamProtocolType
+{
+    wxSTREAM_PROTOCOL,  // wxFileSystem protocol (should be only one)
+    wxSTREAM_MIMETYPE,  // MIME types the stream handles
+    wxSTREAM_ENCODING,  // Not used for archives
+    wxSTREAM_FILEEXT    // File extensions the stream handles
+};
+
+\end{verbatim}
+
 \wxheading{See also}
 
 \helpref{Archive formats such as zip}{wxarc}\\
 \helpref{Generic archive programming}{wxarcgeneric}\\
 \helpref{wxArchiveEntry}{wxarchiveentry}\\
 \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\
-\helpref{wxArchiveOutputStream}{wxarchiveoutputstream}
+\helpref{wxArchiveOutputStream}{wxarchiveoutputstream}\\
+\helpref{wxFilterClassFactory}{wxfilterclassfactory}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -43,6 +67,54 @@ will use when translating meta-data. The initial default, set by the
 constructor, is wxConvLocal.
 
 
+\membersection{wxArchiveClassFactory::CanHandle}\label{wxarchiveclassfactorycanhandle}
+
+\constfunc{bool}{CanHandle}{\param{const wxChar* }{protocol}, \param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
+
+Returns true if this factory can handle the given protocol, MIME type
+or file extension.
+
+When using wxSTREAM\_FILEEXT for the second parameter, the first parameter
+can be a complete filename rather than just an extension.
+
+
+\membersection{wxArchiveClassFactory::Find}\label{wxarchiveclassfactoryfind}
+
+\func{static const wxArchiveClassFactory*}{Find}{\param{const wxChar* }{protocol}, \param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
+
+A static member that finds a factory that can handle a given protocol, MIME
+type or file extension.  Returns a pointer to the class factory if found, or
+NULL otherwise. It does not give away ownership of the factory.
+
+When using wxSTREAM\_FILEEXT for the second parameter, the first parameter
+can be a complete filename rather than just an extension.
+
+
+\membersection{wxArchiveClassFactory::GetFirst/GetNext}\label{wxarchiveclassfactorygetfirst}
+
+\func{static const wxArchiveClassFactory*}{GetFirst}{\void}
+
+\constfunc{const wxArchiveClassFactory*}{GetNext}{\void}
+
+GetFirst and GetNext can be used to enumerate the available factories.
+
+For example, to list them:
+
+\begin{verbatim}
+    wxString list;
+    const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
+
+    while (factory) {
+        list << factory->GetProtocol() << _T("\n");
+        factory = factory->GetNext();
+    }
+
+\end{verbatim}
+
+GetFirst()/GetNext() return a pointer to a factory or NULL if no more
+are available. They do not give away ownership of the factory.
+
+
 \membersection{wxArchiveClassFactory::GetInternalName}\label{wxarchiveclassfactorygetinternalname}
 
 \constfunc{wxString}{GetInternalName}{\param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
@@ -52,6 +124,34 @@ for example
  \helpref{wxZipEntry::GetInternalName()}{wxzipentrygetinternalname}.
 
 
+\membersection{wxArchiveClassFactory::GetProtocol}\label{wxarchiveclassfactorygetprotocol}
+
+\constfunc{wxString}{GetProtocol}{\void}
+
+Returns the wxFileSystem protocol supported by this factory. Equivalent
+to wxString(*GetProtcols()).
+
+
+\membersection{wxArchiveClassFactory::GetProtocols}\label{wxarchiveclassfactorygetprotocols}
+
+\constfunc{const wxChar * const*}{GetProtocols}{\param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
+
+Returns the protocols, MIME types or file extensions supported by this
+factory, as an array of null terminated strings. It does not give away
+ownership of the array or strings.
+
+For example, to list the file extensions a factory supports:
+
+\begin{verbatim}
+    wxString list;
+    const wxChar *const *p;
+
+    for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
+        list << *p << _T("\n");
+
+\end{verbatim}
+
+
 \membersection{wxArchiveClassFactory::NewEntry}\label{wxarchiveclassfactorynewentry}
 
 \constfunc{wxArchiveEntry*}{NewEntry}{\void}
@@ -66,9 +166,45 @@ appropriate type.
 
 \constfunc{wxArchiveOutputStream*}{NewStream}{\param{wxOutputStream\& }{stream}}
 
-Create a new \helpref{wxArchiveInputStream}{wxarchiveinputstream}
-or \helpref{wxArchiveOutputStream}{wxarchiveoutputstream} of the
-appropriate type.
+\constfunc{wxArchiveInputStream*}{NewStream}{\param{wxInputStream* }{stream}}
+
+\constfunc{wxArchiveOutputStream*}{NewStream}{\param{wxOutputStream* }{stream}}
+
+Create a new input or output stream to read or write an archive.
+
+If the parent stream is passed as a pointer then the new archive stream
+takes ownership of it. If it is passed by reference then it does not.
+
+
+\membersection{wxArchiveClassFactory::PushFront}\label{wxarchiveclassfactorypushfront}
+
+\func{void}{PushFront}{\void}
+
+Adds this class factory to the list returned
+by \helpref{GetFirst()/GetNext()}{wxarchiveclassfactorygetfirst}.
+
+It is not necessary to do this to use the archive streams. It is usually
+used when implementing streams, typically the implementation will 
+add a static instance of its factory class.
+
+It can also be used to change the order of a factory already in the list,
+bringing it to the front. This isn't a thread safe operation
+so can't be done when other threads are running that will be using the list.
+
+The list does not take ownership of the factory.
+
+
+\membersection{wxArchiveClassFactory::Remove}\label{wxarchiveclassfactoryremove}
+
+\func{void}{Remove}{\void}
+
+Removes this class factory from the list returned
+by \helpref{GetFirst()/GetNext()}{wxarchiveclassfactorygetfirst}.
+
+Removing from the list isn't a thread safe operation
+so can't be done when other threads are running that will be using the list.
+
+The list does not own the factories, so removing a factory does not delete it.
 
 
 %
diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index 67d99fc7f0..6f50161a29 100644
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -142,6 +142,7 @@
 \input filesys.tex
 \input filesysh.tex
 \input filetype.tex
+\input fltfactory.tex
 \input fltinstr.tex
 \input fltoutst.tex
 \input fdrepdlg.tex
diff --git a/docs/latex/wx/fltfactory.tex b/docs/latex/wx/fltfactory.tex
new file mode 100644
index 0000000000..662f71da3c
--- /dev/null
+++ b/docs/latex/wx/fltfactory.tex
@@ -0,0 +1,186 @@
+%
+% automatically generated by HelpGen $Revision$ from
+% include/wx/stream.h at 28/Oct/06 18:49:10
+%
+
+\section{\class{wxFilterClassFactory}}\label{wxfilterclassfactory}
+
+Allows the creation of filter streams to handle compression formats such
+as gzip and bzip2.
+
+For example, given a filename you can search for a factory that will
+handle it and create a stream to decompress it:
+
+\begin{verbatim}
+    factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
+    if (factory)
+        stream = factory->NewStream(new wxFFileInputStream(filename));
+
+\end{verbatim}
+
+\helpref{Find()}{wxfilterclassfactoryfind} can also search
+for a factory by MIME type, HTTP encoding or by wxFileSystem protocol.
+The available factories can be enumerated
+using \helpref{GetFirst() and GetNext()}{wxfilterclassfactorygetfirst}.
+
+\wxheading{Derived from}
+
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/stream.h>
+
+\wxheading{Data structures}
+
+\begin{verbatim}
+enum wxStreamProtocolType
+{
+    wxSTREAM_PROTOCOL,  // wxFileSystem protocol (should be only one)
+    wxSTREAM_MIMETYPE,  // MIME types the stream handles
+    wxSTREAM_ENCODING,  // The HTTP Content-Encodings the stream handles
+    wxSTREAM_FILEEXT    // File extensions the stream handles
+};
+
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxFilterInputStream}{wxfilterinputstream}\\
+\helpref{wxFilterOutputStream}{wxfilteroutputstream}\\
+\helpref{wxArchiveClassFactory}{wxarchiveclassfactory}\\
+\helpref{Archive formats such as zip}{wxarc}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxFilterClassFactory::CanHandle}\label{wxfilterclassfactorycanhandle}
+
+\constfunc{bool}{CanHandle}{\param{const wxChar* }{protocol}, \param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
+
+Returns true if this factory can handle the given protocol, MIME type, HTTP
+encoding or file extension.
+
+When using wxSTREAM\_FILEEXT for the second parameter, the first parameter
+can be a complete filename rather than just an extension.
+
+
+\membersection{wxFilterClassFactory::Find}\label{wxfilterclassfactoryfind}
+
+\func{static const wxFilterClassFactory*}{Find}{\param{const wxChar* }{protocol}, \param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
+
+A static member that finds a factory that can handle a given protocol, MIME
+type, HTTP encoding or file extension.  Returns a pointer to the class
+factory if found, or NULL otherwise. It does not give away ownership of the
+factory.
+
+When using wxSTREAM\_FILEEXT for the second parameter, the first parameter
+can be a complete filename rather than just an extension.
+
+
+\membersection{wxFilterClassFactory::GetFirst/GetNext}\label{wxfilterclassfactorygetfirst}
+
+\func{static const wxFilterClassFactory*}{GetFirst}{\void}
+
+\constfunc{const wxFilterClassFactory*}{GetNext}{\void}
+
+GetFirst and GetNext can be used to enumerate the available factories.
+
+For example, to list them:
+
+\begin{verbatim}
+    wxString list;
+    const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
+
+    while (factory) {
+        list << factory->GetProtocol() << _T("\n");
+        factory = factory->GetNext();
+    }
+
+\end{verbatim}
+
+GetFirst()/GetNext() return a pointer to a factory or NULL if no more
+are available. They do not give away ownership of the factory.
+
+
+\membersection{wxFilterClassFactory::GetProtocol}\label{wxfilterclassfactorygetprotocol}
+
+\constfunc{wxString}{GetProtocol}{\void}
+
+Returns the wxFileSystem protocol supported by this factory. Equivalent
+to wxString(*GetProtcols()).
+
+
+\membersection{wxFilterClassFactory::GetProtocols}\label{wxfilterclassfactorygetprotocols}
+
+\constfunc{const wxChar * const*}{GetProtocols}{\param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
+
+Returns the protocols, MIME types, HTTP encodings or file extensions
+supported by this factory, as an array of null terminated strings. It does
+not give away ownership of the array or strings.
+
+For example, to list the file extensions a factory supports:
+
+\begin{verbatim}
+    wxString list;
+    const wxChar *const *p;
+
+    for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
+        list << *p << _T("\n");
+
+\end{verbatim}
+
+
+\membersection{wxFilterClassFactory::NewStream}\label{wxfilterclassfactorynewstream}
+
+\constfunc{wxFilterInputStream*}{NewStream}{\param{wxInputStream\& }{stream}}
+
+\constfunc{wxFilterOutputStream*}{NewStream}{\param{wxOutputStream\& }{stream}}
+
+\constfunc{wxFilterInputStream*}{NewStream}{\param{wxInputStream* }{stream}}
+
+\constfunc{wxFilterOutputStream*}{NewStream}{\param{wxOutputStream* }{stream}}
+
+Create a new input or output stream to decompress or compress a given stream.
+
+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.
+
+
+\membersection{wxFilterClassFactory::PopExtension}\label{wxfilterclassfactorypopextension}
+
+\constfunc{wxString}{PopExtension}{\param{const wxString\& }{location}}
+
+Remove the file extension of {\it location} if it is one of the file
+extensions handled by this factory.
+
+
+\membersection{wxFilterClassFactory::PushFront}\label{wxfilterclassfactorypushfront}
+
+\func{void}{PushFront}{\void}
+
+Adds this class factory to the list returned
+by \helpref{GetFirst()/GetNext()}{wxfilterclassfactorygetfirst}.
+
+It is not necessary to do this to use the filter streams. It is usually
+used when implementing streams, typically the implementation will 
+add a static instance of its factory class.
+
+It can also be used to change the order of a factory already in the list,
+bringing it to the front. This isn't a thread safe operation
+so can't be done when other threads are running that will be using the list.
+
+The list does not take ownership of the factory.
+
+
+\membersection{wxFilterClassFactory::Remove}\label{wxfilterclassfactoryremove}
+
+\func{void}{Remove}{\void}
+
+Removes this class factory from the list returned
+by \helpref{GetFirst()/GetNext()}{wxfilterclassfactorygetfirst}.
+
+Removing from the list isn't a thread safe operation
+so can't be done when other threads are running that will be using the list.
+
+The list does not own the factories, so removing a factory does not delete it.
diff --git a/docs/latex/wx/fltinstr.tex b/docs/latex/wx/fltinstr.tex
index 0be10d46da..f521c0ddff 100644
--- a/docs/latex/wx/fltinstr.tex
+++ b/docs/latex/wx/fltinstr.tex
@@ -21,6 +21,11 @@ from another stream and pass it to the requester.
 The interface of this class is the same as that of wxInputStream. Only a constructor
 differs and it is documented below.
 
+\wxheading{See also}
+
+\helpref{wxFilterClassFactory}{wxfilterclassfactory}\\
+\helpref{wxFilterOutputStream}{wxfilteroutputstream}
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 % -----------
@@ -30,5 +35,10 @@ differs and it is documented below.
 
 \func{}{wxFilterInputStream}{\param{wxInputStream\&}{ stream}}
 
+\func{}{wxFilterInputStream}{\param{wxInputStream*}{ stream}}
+
 Initializes a "filter" stream.
 
+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.
+
diff --git a/docs/latex/wx/fltoutst.tex b/docs/latex/wx/fltoutst.tex
index 0b0f95aaf3..949a2b667b 100644
--- a/docs/latex/wx/fltoutst.tex
+++ b/docs/latex/wx/fltoutst.tex
@@ -22,6 +22,11 @@ stream.
 The use of this class is exactly the same as of wxOutputStream. Only a constructor
 differs and it is documented below.
 
+\wxheading{See also}
+
+\helpref{wxFilterClassFactory}{wxfilterclassfactory}\\
+\helpref{wxFilterInputStream}{wxfilterinputstream}
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 % -----------
@@ -31,5 +36,10 @@ differs and it is documented below.
 
 \func{}{wxFilterOutputStream}{\param{wxOutputStream\&}{ stream}}
 
+\func{}{wxFilterOutputStream}{\param{wxOutputStream*}{ stream}}
+
 Initializes a "filter" stream.
 
+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.
+
diff --git a/docs/latex/wx/strmzlib.tex b/docs/latex/wx/strmzlib.tex
index 722011a33a..eda8d2f207 100644
--- a/docs/latex/wx/strmzlib.tex
+++ b/docs/latex/wx/strmzlib.tex
@@ -30,6 +30,11 @@ not supported, it always returns $0$.
 
 \func{}{wxZlibInputStream}{\param{wxInputStream\&}{ stream}, \param{int}{ flags = wxZLIB\_AUTO}}
 
+\func{}{wxZlibInputStream}{\param{wxInputStream*}{ stream}, \param{int}{ flags = wxZLIB\_AUTO}}
+
+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 {\it 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.
@@ -101,11 +106,16 @@ The stream is not seekable, \helpref{SeekO()}{wxoutputstreamseeko} returns
 
 \func{}{wxZlibOutputStream}{\param{wxOutputStream\&}{ stream}, \param{int}{ level = -1}, \param{int}{ flags = wxZLIB\_ZLIB}}
 
+\func{}{wxZlibOutputStream}{\param{wxOutputStream*}{ stream}, \param{int}{ level = -1}, \param{int}{ flags = wxZLIB\_ZLIB}}
+
 Creates a new write-only compressed stream. {\it 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.
+
 The {\it flags} wxZLIB\_ZLIB and wxZLIB\_GZIP specify whether the output data
 will be in zlib or gzip format. wxZLIB\_ZLIB is the default.
 
diff --git a/docs/latex/wx/zipstrm.tex b/docs/latex/wx/zipstrm.tex
index e60b07afd8..b7cbc612be 100644
--- a/docs/latex/wx/zipstrm.tex
+++ b/docs/latex/wx/zipstrm.tex
@@ -462,13 +462,18 @@ typedef wxZipEntry entry_type
 
 \func{}{wxZipInputStream}{\param{wxInputStream\& }{stream}, \param{wxMBConv\& }{conv = wxConvLocal}}
 
+\func{}{wxZipInputStream}{\param{wxInputStream*}{stream}, \param{wxMBConv\& }{conv = wxConvLocal}}
+
 Constructor. In a Unicode build the second parameter {\tt 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.
+
 \func{}{wxZipInputStream}{\param{const wxString\& }{archive}, \param{const wxString\& }{file}}
 
-Compatibility constructor.
+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,
@@ -608,10 +613,15 @@ entry and begins the next.
 
 \func{}{wxZipOutputStream}{\param{wxOutputStream\& }{stream}, \param{int }{level = -1}, \param{wxMBConv\& }{conv = wxConvLocal}}
 
+\func{}{wxZipOutputStream}{\param{wxOutputStream*}{stream}, \param{int }{level = -1}, \param{wxMBConv\& }{conv = wxConvLocal}}
+
 Constructor. {\tt 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.
 
+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 {\tt conv} is used to translate
 the filename and comment fields to Unicode. It has no effect on the
 stream's data.
-- 
2.50.0

