Add test for absence of events from wxSpinCtrlDouble ctor.

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

diff --git a/interface/wx/dir.h b/interface/wx/dir.h
index cae45e337be05c316fd7394a29f97479b4f96f8e..eae73a235b75a170922c7b0654e0d11cdc117e6a 100644 (file)
--- a/interface/wx/dir.h
+++ b/interface/wx/dir.h
@@ -2,8 +2,7 @@
 // Name:        dir.h
 // Purpose:     interface of wxDir and wxDirTraverser
 // Author:      wxWidgets team
 // Name:        dir.h
 // Purpose:     interface of wxDir and wxDirTraverser
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -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 "..".
 
 {
     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
 };
 
     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
 };
 


@@ -158,11 +179,23 @@ public:
     wxDir(const wxString& dir);
 
     /**
     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();
 
     */
     ~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.
     */
     /**
         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.
         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()
     */
 
         @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).
         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()
     */
 
         @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.
     /**
         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;
 
     /**
     */
     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;
 
     */
     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().
     /**
         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.
 
         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
         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;
 
     */
     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.
     /**
         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);
 
     /**
     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
         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.
 
 
         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,
         @see GetAllFiles()
     */
     size_t Traverse(wxDirTraverser& sink,