X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..4e621d24713f971d1a2d440f79ccc4593aede4b6:/interface/wx/filesys.h diff --git a/interface/wx/filesys.h b/interface/wx/filesys.h index c9d534e86a..94ea102527 100644 --- a/interface/wx/filesys.h +++ b/interface/wx/filesys.h @@ -3,7 +3,7 @@ // Purpose: interface of wxFileSystem, wxFileSystemHandler, wxFSFile // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -19,7 +19,6 @@ enum wxFileSystemOpenFlags /** @class wxFileSystem - @wxheader{filesys.h} This class provides an interface for opening files on different file systems. It can handle absolute and/or local filenames. @@ -37,6 +36,11 @@ class wxFileSystem : public wxObject public: /** Constructor. + + The initial current path of this object will be empty + (i.e. GetPath() == wxEmptyString) which means that e.g. OpenFile() + or FindFirst() functions will use current working directory as + current path (see also wxGetCwd). */ wxFileSystem(); @@ -55,8 +59,13 @@ public: handlers are deleted in wxFileSystem's destructor so that you don't have to care about it. */ - static void AddHandler(wxFileSystemHandler handler); + static void AddHandler(wxFileSystemHandler* handler); + /** + Remove a filesystem handler from the list of handlers. + */ + static wxFileSystemHandler* RemoveHandler(wxFileSystemHandler *handler); + /** Sets the current location. @a location parameter passed to OpenFile() is relative to this path. @@ -101,14 +110,14 @@ public: If the file is found in any directory, returns @true and the full path of the file in @a str, otherwise returns @false and doesn't modify @a str. - @param str + @param pStr Receives the full path of the file, must not be @NULL @param path wxPATH_SEP-separated list of directories @param file the name of the file to look for */ - bool FindFileInPath(wxString str, const wxString& path, + bool FindFileInPath(wxString* pStr, const wxString& path, const wxString& file); /** @@ -132,7 +141,7 @@ public: /** Returns the actual path (set by wxFileSystem::ChangePathTo). */ - wxString GetPath(); + wxString GetPath() const; /** This static function returns @true if there is a registered handler which can @@ -156,6 +165,11 @@ public: Passing @e "wxFS_READ | wxFS_SEEKABLE" for @a flags will back a stream that is not natively seekable with memory or a file and return a stream that is always seekable. + + @note + The @a location argument is, despite this method's name @em not + a filename. It is a "location", aka wxFileSystem URL (see + @ref overview_fs). */ wxFSFile* OpenFile(const wxString& location, int flags = wxFS_READ); @@ -171,10 +185,9 @@ public: /** @class wxFSFile - @wxheader{filesys.h} This class represents a single file opened by wxFileSystem. - It provides more information than wxWindow's input stream + It provides more informations than wxWidgets' input streams (stream, filename, mime type, anchor). @note Any pointer returned by a method of wxFSFile is valid only as long as @@ -184,7 +197,7 @@ public: ten identical pointers. @library{wxbase} - @category{vfs} + @category{vfs,file} @see wxFileSystemHandler, wxFileSystem, @ref overview_fs */ @@ -226,19 +239,21 @@ public: not be empty in this case). @param anchor Anchor. See GetAnchor() for details. + @param modif + Modification date and time for this file. */ - wxFSFile(wxInputStream stream, const wxString& loc, - const wxString& mimetype, - const wxString& anchor, wxDateTime modif); + wxFSFile(wxInputStream* stream, const wxString& location, + const wxString& mimetype, const wxString& anchor, + wxDateTime modif); /** Detaches the stream from the wxFSFile object. That is, the - stream obtained with GetStream() will continue its existance + stream obtained with GetStream() will continue its existence after the wxFSFile object is deleted. You will have to delete the stream yourself. */ - void DetachStream(); + wxInputStream* DetachStream(); /** Returns anchor (if present). The term of @b anchor can be easily @@ -300,7 +315,6 @@ public: /** @class wxFileSystemHandler - @wxheader{filesys.h} Classes derived from wxFileSystemHandler are used to access virtual file systems. @@ -327,7 +341,7 @@ public: @beginWxPerlOnly In wxPerl, you need to derive your file system handler class - from Wx::PlFileSystemHandler. + from @c Wx::PlFileSystemHandler. @endWxPerlOnly @library{wxbase} @@ -357,7 +371,7 @@ public: Must be overridden in derived handlers. */ - virtual bool CanOpen(const wxString& location); + virtual bool CanOpen(const wxString& location) = 0; /** Works like ::wxFindFirstFile(). @@ -380,39 +394,53 @@ public: virtual wxString FindNext(); /** - Returns the anchor if present in the location. - See wxFSFile::GetAnchor for details. + Returns the MIME type based on @b extension of @a location. + (While wxFSFile::GetMimeType() returns real MIME type - either + extension-based or queried from HTTP.) Example: @code - GetAnchor("index.htm#chapter2") == "chapter2" + GetMimeTypeFromExt("index.htm") == "text/html" @endcode + */ + static wxString GetMimeTypeFromExt(const wxString& location); - @note the anchor is NOT part of the left location. + /** + Opens the file and returns wxFSFile pointer or @NULL if failed. + Must be overridden in derived handlers. + + @param fs + Parent FS (the FS from that OpenFile was called). + See the ZIP handler for details of how to use it. + @param location + The absolute location of file. */ - wxString GetAnchor(const wxString& location) const; + virtual wxFSFile* OpenFile(wxFileSystem& fs, const wxString& location) = 0; + +protected: /** - Returns the left location string extracted from @e location. + Returns the anchor if present in the location. + See wxFSFile::GetAnchor for details. Example: @code - GetLeftLocation("file:myzipfile.zip#zip:index.htm") == "file:myzipfile.zip" + GetAnchor("index.htm#chapter2") == "chapter2" @endcode + + @note the anchor is NOT part of the left location. */ - wxString GetLeftLocation(const wxString& location) const; + static wxString GetAnchor(const wxString& location); /** - Returns the MIME type based on @b extension of @a location. - (While wxFSFile::GetMimeType() returns real MIME type - either - extension-based or queried from HTTP.) + Returns the left location string extracted from @e location. Example: @code - GetMimeTypeFromExt("index.htm") == "text/html" + GetLeftLocation("file:myzipfile.zip#zip:index.htm") == "file:myzipfile.zip" @endcode */ - wxString GetMimeTypeFromExt(const wxString& location); + static wxString GetLeftLocation(const wxString& location); /** Returns the protocol string extracted from @a location. @@ -422,7 +450,7 @@ public: GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip" @endcode */ - wxString GetProtocol(const wxString& location) const; + static wxString GetProtocol(const wxString& location); /** Returns the right location string extracted from @a location. @@ -432,19 +460,44 @@ public: GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm" @endcode */ - wxString GetRightLocation(const wxString& location) const; + static wxString GetRightLocation(const wxString& location); +}; + +/** + Input stream for virtual file stream files. + + The stream reads data from wxFSFile obtained from wxFileSystem. It is + especially useful to allow using virtual files with other wxWidgets + functions and classes working with streams, e.g. for loading images or + animations from virtual files and not only physical ones. + + @library{wxbase} + @category{streams} + + @see wxWrapperInputStream, wxFSFile + + @since 2.9.4 +*/ +class wxFSInputStream : public wxWrapperInputStream +{ +public: /** - Opens the file and returns wxFSFile pointer or @NULL if failed. - Must be overridden in derived handlers. + Create a stream associated with the data of the given virtual file + system file. - @param fs - Parent FS (the FS from that OpenFile was called). - See the ZIP handler for details of how to use it. - @param location - The absolute location of file. + @param filename + The name of the input file passed to wxFileSystem::OpenFile(). + @param flags + Combination of flags from wxFileSystemOpenFlags. ::wxFS_READ is + implied, i.e. it is always added to the flags value. + + Use wxStreamBase::IsOk() to verify if the constructor succeeded. */ - virtual wxFSFile* OpenFile(wxFileSystem& fs, - const wxString& location); -}; + wxFileInputStream(const wxString& filename, int flags = 0); + /** + Returns @true if the stream is initialized and ready. + */ + bool IsOk() const; +};