synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / filesys.h

diff --git a/interface/wx/filesys.h b/interface/wx/filesys.h
index c872dbafc87ac1b93d01581f68248bffda34a50f..94ea102527b8751a13667246ac238856f5aa8431 100644 (file)
--- 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$
 // Purpose:     interface of wxFileSystem, wxFileSystemHandler, wxFSFile
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -36,6 +36,11 @@ class wxFileSystem : public wxObject
 public:
     /**
         Constructor.
 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();
 
     */
     wxFileSystem();
 


@@ -54,8 +59,13 @@ public:
               handlers are deleted in wxFileSystem's destructor so that you
               don't have to care about it.
     */
               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.
     /**
         Sets the current location. @a location parameter passed to OpenFile() is
         relative to this path.


@@ -100,7 +110,7 @@ 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.
 
         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
             Receives the full path of the file, must not be @NULL
         @param path
             wxPATH_SEP-separated list of directories


@@ -155,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.
         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);
     */
     wxFSFile* OpenFile(const wxString& location,
                        int flags = wxFS_READ);


@@ -172,7 +187,7 @@ public:
     @class wxFSFile
 
     This class represents a single file opened by wxFileSystem.
     @class wxFSFile
 
     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
     (stream, filename, mime type, anchor).
 
     @note Any pointer returned by a method of wxFSFile is valid only as long as


@@ -182,7 +197,7 @@ public:
           ten identical pointers.
 
     @library{wxbase}
           ten identical pointers.
 
     @library{wxbase}

-    @category{vfs}
+    @category{vfs,file}

 
     @see wxFileSystemHandler, wxFileSystem, @ref overview_fs
 */
 
     @see wxFileSystemHandler, wxFileSystem, @ref overview_fs
 */


@@ -233,7 +248,7 @@ public:
 
     /**
         Detaches the stream from the wxFSFile object. That is, the
 
     /**
         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.
         after the wxFSFile object is deleted.
 
         You will have to delete the stream yourself.


@@ -326,7 +341,7 @@ public:
 
     @beginWxPerlOnly
     In wxPerl, you need to derive your file system handler class
 
     @beginWxPerlOnly
     In wxPerl, you need to derive your file system handler class

-    from Wx::PlFileSystemHandler.
+    from @c Wx::PlFileSystemHandler.

     @endWxPerlOnly
 
     @library{wxbase}
     @endWxPerlOnly
 
     @library{wxbase}


@@ -378,6 +393,32 @@ public:
     */
     virtual wxString FindNext();
 
     */
     virtual wxString FindNext();
 

+    /**
+        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
+        GetMimeTypeFromExt("index.htm") == "text/html"
+        @endcode
+    */
+    static wxString GetMimeTypeFromExt(const wxString& 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.
+    */
+    virtual wxFSFile* OpenFile(wxFileSystem& fs, const wxString& location) = 0;
+
+protected:
+

     /**
         Returns the anchor if present in the location.
         See wxFSFile::GetAnchor for details.
     /**
         Returns the anchor if present in the location.
         See wxFSFile::GetAnchor for details.


@@ -401,18 +442,6 @@ public:
     */
     static wxString GetLeftLocation(const wxString& location);
 
     */
     static wxString GetLeftLocation(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.)
-
-        Example:
-        @code
-        GetMimeTypeFromExt("index.htm") == "text/html"
-        @endcode
-    */
-    static wxString GetMimeTypeFromExt(const wxString& location);
-

     /**
         Returns the protocol string extracted from @a location.
 
     /**
         Returns the protocol string extracted from @a location.
 


@@ -432,17 +461,43 @@ public:
         @endcode
     */
     static wxString GetRightLocation(const wxString& location);
         @endcode
     */
     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) = 0;
-};
+    wxFileInputStream(const wxString& filename, int flags = 0);

 
 

+    /**
+        Returns @true if the stream is initialized and ready.
+    */
+    bool IsOk() const;
+};