From 716b1f7091622187312a86257eac0570d0ccd8a2 Mon Sep 17 00:00:00 2001 From: Michael Wetherell 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. +\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} + + + +\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.47.2