]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/dir.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / dir.h
index 5a94810604fe982b9323ad2b785273eca7d320ae..eae73a235b75a170922c7b0654e0d11cdc117e6a 100644 (file)
@@ -2,8 +2,7 @@
 // Name:        dir.h
 // Purpose:     interface of wxDir and wxDirTraverser
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -68,7 +67,7 @@ public:
         This is a pure virtual function and must be implemented in the derived
         class.
     */
-    virtual wxDirTraverseResult OnDir(const wxString& dirname);
+    virtual wxDirTraverseResult OnDir(const wxString& dirname) = 0;
 
     /**
         This function is called for each file. It may return ::wxDIR_STOP to
@@ -78,7 +77,7 @@ public:
         This is a pure virtual function and must be implemented in the derived
         class.
     */
-    virtual wxDirTraverseResult OnFile(const wxString& filename);
+    virtual wxDirTraverseResult OnFile(const wxString& filename) = 0;
 
     /**
         This function is called for each directory which we failed to open for
@@ -94,16 +93,38 @@ public:
 
 
 /**
-    These flags define what kind of filenames are included in the list of files
-    enumerated by wxDir::GetFirst() and wxDir::GetNext().
+    These flags affect the behaviour of GetFirst/GetNext() and Traverse(),
+    determining what types are included in the list of items they produce.
 */
-enum
+enum wxDirFlags
 {
     wxDIR_FILES     = 0x0001,   ///< Includes files.
     wxDIR_DIRS      = 0x0002,   ///< Includes directories.
     wxDIR_HIDDEN    = 0x0004,   ///< Includes hidden files.
     wxDIR_DOTDOT    = 0x0008,   ///< Includes "." and "..".
 
+    /**
+        Don't follow symbolic links during the directory traversal.
+
+        This flag is ignored under systems not supporting symbolic links (i.e.
+        non-Unix ones).
+
+        Notice that this flag is @e not included in wxDIR_DEFAULT and so the
+        default behaviour of wxDir::Traverse() is to follow symbolic links,
+        even if they lead outside of the directory being traversed.
+
+        @since 2.9.5
+     */
+    wxDIR_NO_FOLLOW = 0x0010,
+
+    /**
+        Default directory traversal flags include both files and directories,
+        even hidden.
+
+        Notice that by default wxDIR_NO_FOLLOW is @e not included, meaning that
+        symbolic links are followed by default. If this is not desired, you
+        must pass that flag explicitly.
+     */
     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
 };
 
@@ -158,11 +179,23 @@ public:
     wxDir(const wxString& dir);
 
     /**
-        Destructor cleans up the associated resources. It is not virtual and so
-        this class is not meant to be used polymorphically.
+        Destructor cleans up the associated resources by calling Close().
+
+        It is not virtual and so this class is not meant to be used
+        polymorphically.
     */
     ~wxDir();
 
+    /**
+        Close the directory.
+
+        The object can't be used after closing it, but Open() may be called
+        again to reopen it later.
+
+        @since 2.9.5
+    */
+    void Close();
+
     /**
         Test for existence of a directory with the given name.
     */
@@ -177,6 +210,7 @@ public:
         includes ::wxDIR_DIRS and so the function recurses into the
         subdirectories but if this flag is not specified, the function
         restricts the search only to the directory @a dirname itself.
+        See ::wxDirFlags for the list of the possible flags.
 
         @see Traverse()
     */
@@ -193,6 +227,11 @@ public:
         The @a flags parameter should always include ::wxDIR_FILES or the array
         would be unchanged and should include ::wxDIR_DIRS flag to recurse into
         subdirectories (both flags are included in the value by default).
+        See ::wxDirFlags for the list of the possible flags.
+        
+        @return Returns the total number of files found while traversing
+                the directory @a dirname (i.e. the number of entries appended
+                to the @a files array).
 
         @see Traverse()
     */
@@ -203,17 +242,38 @@ public:
     /**
         Start enumerating all files matching @a filespec (or all files if it is
         empty) and @e flags, return @true on success.
+        See ::wxDirFlags for the list of the possible flags.
     */
     bool GetFirst(wxString* filename,
                   const wxString& filespec = wxEmptyString,
                   int flags = wxDIR_DEFAULT) const;
 
     /**
-        Returns the name of the directory itself. The returned string does not
-        have the trailing path separator (slash or backslash).
+        Returns the name of the directory itself.
+
+        The returned string does not have the trailing path separator (slash or
+        backslash).
+
+        Notice that in spite of this the last character of the returned string
+        can still be the path separator if this directory is the root one.
+        Because of this, don't append ::wxFILE_SEP_PATH to the returned value
+        if you do need a slash-terminated directory name but use
+        GetNameWithSep() instead to avoid having duplicate consecutive slashes.
     */
     wxString GetName() const;
 
+    /**
+        Returns the name of the directory with the path separator appended.
+
+        The last character of the returned string is always ::wxFILE_SEP_PATH
+        unless the string is empty, indicating that this directory is invalid.
+
+        @see GetName()
+
+        @since 2.9.4
+     */
+    wxString GetNameWithSep() const;
+
     /**
         Continue enumerating files which satisfy the criteria specified by the
         last call to GetFirst().
@@ -224,7 +284,7 @@ public:
         Returns the size (in bytes) of all files recursively found in @c dir or
         @c wxInvalidSize in case of error.
 
-        In case it happens that while traversing folders a file's size can not
+        In case it happens that while traversing folders a file's size cannot
         be read, that file is added to the @a filesSkipped array, if not @NULL,
         and then skipped. This usually happens with some special folders which
         are locked by the operating system or by another process. Remember that
@@ -257,6 +317,15 @@ public:
     */
     bool IsOpened() const;
 
+    /**
+        Creates a directory.
+        
+        This is just an alias for wxFileName::Mkdir(); refer to that function
+        for more info.
+    */
+    static bool Make(const wxString &dir, int perm = wxS_DIR_DEFAULT,
+                     int flags = 0);
+
     /**
         Open the directory for enumerating, returns @true on success or @false
         if an error occurred.
@@ -264,23 +333,36 @@ public:
     bool Open(const wxString& dir);
 
     /**
-        Enumerate all files and directories under the given directory
-        recursively calling the element of the provided wxDirTraverser object
-        for each of them.
+        Removes a directory.
+        
+        This is just an alias for wxFileName::Rmdir(); refer to that function
+        for more info.
+    */
+    static bool Remove(const wxString &dir, int flags = 0);
+    
+    /**
+        Enumerate all files and directories under the given directory.
+
+        If @a flags contains ::wxDIR_DIRS this enumeration is recursive, i.e.
+        all the subdirectories of the given one and the files inside them will
+        be traversed. Otherwise only the files in this directory itself are.
 
-        More precisely, the function will really recurse into subdirectories if
-        @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but
-        still possibly recurse into subdirectories) if ::wxDIR_FILES flag is
-        given.
+        If @a flags doesn't contain ::wxDIR_FILES then only subdirectories are
+        examined but not normal files. It doesn't make sense to not specify
+        either ::wxDIR_DIRS or ::wxDIR_FILES and usually both of them should be
+        specified, as is the case by default.
 
-        For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()"
+        For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()"
         is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
         for every file. Depending on the return value, the enumeration may
-        continue or stop.
+        continue or stop. If entering a subdirectory fails, @ref
+        wxDirTraverser::OnOpenError() "sink.OnOpenError()" is called.
 
         The function returns the total number of files found or @c "(size_t)-1"
         on error.
 
+        See ::wxDirFlags for the full list of the possible flags.
+
         @see GetAllFiles()
     */
     size_t Traverse(wxDirTraverser& sink,