X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/dir.h diff --git a/interface/wx/dir.h b/interface/wx/dir.h index 82b40531ca..d9a9c0dae7 100644 --- 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 -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -18,7 +17,6 @@ enum wxDirTraverseResult /** @class wxDirTraverser - @wxheader{dir.h} wxDirTraverser is an abstract interface which must be implemented by objects passed to wxDir::Traverse() function. @@ -69,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 @@ -79,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 @@ -95,22 +93,43 @@ 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 }; /** @class wxDir - @wxheader{dir.h} wxDir is a portable equivalent of Unix open/read/closedir functions which allow enumerating of the files in a directory. wxDir allows to enumerate @@ -160,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. */ @@ -179,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() */ @@ -195,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() */ @@ -205,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 @c 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 @c 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(). @@ -226,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 @@ -259,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. @@ -266,27 +333,40 @@ 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, const wxString& filespec = wxEmptyString, - int flags = wxDIR_DEFAULT); + int flags = wxDIR_DEFAULT) const; };