documented VFS handlers

[wxWidgets.git] / docs / latex / wx / filesysh.tex

%
% automatically generated by HelpGen from
% filesystemhandler.tex at 21/Mar/99 23:00:52
%

\section{\class{wxFileSystemHandler}}\label{wxfilesystemhandler}

Classes derived from wxFileSystemHandler are used
to access virtual file systems. Its public interface consists
of two methods: \helpref{CanOpen}{wxfilesystemhandlercanopen} 
and \helpref{OpenFile}{wxfilesystemhandleropenfile}. 
It provides additional protected methods to simplify the process
of opening the file: GetProtocol, GetLeftLocation, GetRightLocation,
GetAnchor, GetMimeTypeFromExt.

Please have a look at \helpref{overview}{fs} if you don't know how locations
are constructed.

Also consult \helpref{list of available handlers}{fs}.

\wxheading{Notes}

\begin{itemize}\itemsep=0pt
\item The handlers are shared by all instances of wxFileSystem.
\item wxHTML library provides handlers for local files and HTTP or FTP protocol
\item The {\it location} parameter passed to OpenFile or CanOpen methods
is always an {\bf absolute} path. You don't need to check the FS's current path.
\end{itemize}

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/filesys.h>

\wxheading{See also}

\helpref{wxFileSystem}{wxfilesystem}, 
\helpref{wxFSFile}{wxfsfile}, 
\helpref{Overview}{fs}

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxFileSystemHandler::wxFileSystemHandler}\label{wxfilesystemhandlerwxfilesystemhandler}

\func{}{wxFileSystemHandler}{\void}

Constructor.

\membersection{wxFileSystemHandler::CanOpen}\label{wxfilesystemhandlercanopen}

\func{virtual bool}{CanOpen}{\param{const wxString\& }{location}}

Returns TRUE if the handler is able to open this file. This function doesn't
check whether the file exists or not, it only checks if it knows the protocol.
Example:

\begin{verbatim}
bool MyHand::CanOpen(const wxString& location) 
{
    return (GetProtocol(location) == "http");
}
\end{verbatim}

Must be overridden in derived handlers.

\membersection{wxFileSystemHandler::GetAnchor}\label{wxfilesystemhandlergetanchor}

\constfunc{wxString}{GetAnchor}{\param{const wxString\& }{location}}

Returns the anchor if present in the location.
See \helpref{wxFSFile}{wxfsfilegetanchor} for details.

Example: GetAnchor("index.htm\#chapter2") == "chapter2"

{\bf Note:} the anchor is NOT part of the left location.

\membersection{wxFileSystemHandler::GetLeftLocation}\label{wxfilesystemhandlergetleftlocation}

\constfunc{wxString}{GetLeftLocation}{\param{const wxString\& }{location}}

Returns the left location string extracted from {\it location}. 

Example: GetLeftLocation("file:myzipfile.zip\#zip:index.htm") == "file:myzipfile.zip"

\membersection{wxFileSystemHandler::GetMimeTypeFromExt}\label{wxfilesystemhandlergetmimetypefromext}

\func{wxString}{GetMimeTypeFromExt}{\param{const wxString\& }{location}}

Returns the MIME type based on {\bf extension} of {\it location}. (While wxFSFile::GetMimeType
returns real MIME type - either extension-based or queried from HTTP.)

Example : GetMimeTypeFromExt("index.htm") == "text/html"

\membersection{wxFileSystemHandler::GetProtocol}\label{wxfilesystemhandlergetprotocol}

\constfunc{wxString}{GetProtocol}{\param{const wxString\& }{location}}

Returns the protocol string extracted from {\it location}. 

Example: GetProtocol("file:myzipfile.zip\#zip:index.htm") == "zip"

\membersection{wxFileSystemHandler::GetRightLocation}\label{wxfilesystemhandlergetrightlocation}

\constfunc{wxString}{GetRightLocation}{\param{const wxString\& }{location}}

Returns the right location string extracted from {\it location}. 

Example : GetRightLocation("file:myzipfile.zip\#zip:index.htm") == "index.htm"

\membersection{wxFileSystemHandler::FindFirst}\label{wxfilesystemhandlerfindfirst}

\func{virtual wxString}{FindFirst}{\param{const wxString\& }{wildcard}, \param{int }{flags = 0}}

Works like \helpref{wxFindFirstFile}{wxfindfirstfile}. Returns name of the first
filename (withing filesystem's current path) that matches {\it wildcard}. {\it flags} may be one of
wxFILE (only files), wxDIR (only directories) or 0 (both).

This method is only called if \helpref{CanOpen}{wxfilesystemhandlercanopen} returns TRUE.

\membersection{wxFileSystemHandler::FindNext}\label{wxfilesystemhandlerfindnext}

\func{virtual wxString}{FindNext}{\void}

Returns next filename that matches parameters passed to \helpref{FindFirst}{wxfilesystemfindfirst}.

This method is only called if \helpref{CanOpen}{wxfilesystemhandlercanopen} returns TRUE and FindFirst
returned a non-empty string.

\membersection{wxFileSystemHandler::OpenFile}\label{wxfilesystemhandleropenfile}

\func{virtual wxFSFile*}{OpenFile}{\param{wxFileSystem\& }{fs}, \param{const wxString\& }{location}}

Opens the file and returns wxFSFile pointer or NULL if failed.

Must be overridden in derived handlers.

\wxheading{Parameters}

\docparam{fs}{Parent FS (the FS from that OpenFile was called). See ZIP handler
for details of how to use it.}

\docparam{location}{The {\bf absolute} location of file.}