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
This commit is contained in:
Michael Wetherell 2006-10-29 12:56:48 +00:00
parent 64c8307c93
commit 716b1f7091
7 changed files with 374 additions and 11 deletions

View File

@ -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 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.
For example, given a filename you can search for a factory that will
handle it and create a stream to read it:
\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.
%

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.