X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/46263455960bc46a6b2e77d444061b6378fc6373..420455b510fc71f73d1ddfc02dbaf0dfcc8bce1c:/docs/latex/wx/archive.tex?ds=sidebyside diff --git a/docs/latex/wx/archive.tex b/docs/latex/wx/archive.tex index cf4fb20f46..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. % @@ -459,7 +595,7 @@ Construct iterator that returns all the entries in the archive input stream {\it arc}. -\membersection{wxArchiveIterator::operator*}\label{wxarchiveiteratoroperatorunknown} +\membersection{wxArchiveIterator::operator*}\label{wxarchiveiteratoroperatorstar} \constfunc{const T\&}{operator*}{\void} @@ -467,7 +603,7 @@ Returns an entry object from the archive input stream, giving away ownership. -\membersection{wxArchiveIterator::operator++}\label{wxarchiveiteratoroperatorunknown} +\membersection{wxArchiveIterator::operator++}\label{wxarchiveiteratoroperatorincrement} \func{wxArchiveIterator\&}{operator++}{\void}