X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..de022e4f1197d146e9bdd6aeb2ac0ee9cb217737:/interface/dir.h?ds=sidebyside diff --git a/interface/dir.h b/interface/dir.h index 5077125fbc..cb9ca73917 100644 --- a/interface/dir.h +++ b/interface/dir.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dir.h -// Purpose: documentation for wxDirTraverser class +// Purpose: interface of wxDirTraverser // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,128 +9,126 @@ /** @class wxDirTraverser @wxheader{dir.h} - + wxDirTraverser is an abstract interface which must be implemented by objects passed to wxDir::Traverse function. - + Example of use (this works almost like wxDir::GetAllFiles): - + @code class wxDirTraverserSimple : public wxDirTraverser { public: wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } - + virtual wxDirTraverseResult OnFile(const wxString& filename) { m_files.Add(filename); return wxDIR_CONTINUE; } - + virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) { return wxDIR_CONTINUE; } - + private: wxArrayString& m_files; }; - + // get the names of all files in the array wxArrayString files; wxDirTraverserSimple traverser(files); - + wxDir dir(dirname); dir.Traverse(traverser); @endcode - + @library{wxbase} @category{file} */ -class wxDirTraverser +class wxDirTraverser { public: /** - This function is called for each directory. It may return @c wxSIR_STOP + This function is called for each directory. It may return @c wxDIR_STOP to abort traversing completely, @c wxDIR_IGNORE to skip this directory but continue with others or @c wxDIR_CONTINUE to enumerate all files and subdirectories in this directory. - This is a pure virtual function and must be implemented in the derived class. */ virtual wxDirTraverseResult OnDir(const wxString& dirname); /** This function is called for each file. It may return @c wxDIR_STOP to abort - traversing (for example, if the file being searched is found) or + traversing (for example, if the file being searched is found) or @c wxDIR_CONTINUE to proceed. - This is a pure virtual function and must be implemented in the derived class. */ virtual wxDirTraverseResult OnFile(const wxString& filename); /** This function is called for each directory which we failed to open for - enumerating. It may return @c wxSIR_STOP to abort traversing completely, - @c wxDIR_IGNORE to skip this directory but continue with others or + enumerating. It may return @c wxDIR_STOP to abort traversing completely, + @c wxDIR_IGNORE to skip this directory but continue with others or @c wxDIR_CONTINUE to retry opening this directory once again. - The base class version always returns @c wxDIR_IGNORE. */ virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); }; + /** @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 files as well as directories. - - wxDir also provides a flexible way to enumerate files recursively using - wxDir::Traverse or a simpler + + wxDir also provides a flexible way to enumerate files recursively using + wxDir::Traverse or a simpler wxDir::GetAllFiles function. - + Example of use: - + @code wxDir dir(wxGetCwd()); - + if ( !dir.IsOpened() ) { // deal with the error here - wxDir would already log an error message // explaining the exact reason of the failure return; } - + puts("Enumerating object files in current directory:"); - + wxString filename; - + bool cont = dir.GetFirst(, filespec, flags); while ( cont ) { printf("%s\n", filename.c_str()); - + cont = dir.GetNext(); } @endcode - + @library{wxbase} @category{file} */ -class wxDir +class wxDir { public: //@{ /** - Opens the directory for enumeration, use IsOpened() + Opens the directory for enumeration, use IsOpened() to test for errors. */ wxDir(); - wxDir(const wxString& dir); + wxDir(const wxString& dir); //@} /** @@ -147,13 +145,11 @@ public: /** The function returns the path of the first file matching the given @e filespec or an empty string if there are no files matching it. - - The @e flags parameter may or may not include @c wxDIR_FILES, the - function always behaves as if it were specified. By default, @e flags + The @a flags parameter may or may not include @c wxDIR_FILES, the + function always behaves as if it were specified. By default, @a flags includes @c 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 @e dirname itself. - + the directory @a dirname itself. See also: Traverse() */ static wxString FindFirst(const wxString& dirname, @@ -161,45 +157,42 @@ public: int flags = wxDIR_DEFAULT); /** - The function appends the names of all the files under directory @e dirname - to the array @e files (note that its old content is preserved). Only files - matching the @e filespec are taken, with empty spec matching all the files. - - The @e flags parameter should always include @c wxDIR_FILES or the array + The function appends the names of all the files under directory @a dirname + to the array @a files (note that its old content is preserved). Only files + matching the @a filespec are taken, with empty spec matching all the files. + The @a flags parameter should always include @c wxDIR_FILES or the array would be unchanged and should include @c wxDIR_DIRS flag to recurse into subdirectories (both flags are included in the value by default). - See also: Traverse() */ static size_t GetAllFiles(const wxString& dirname, - wxArrayString * files, + wxArrayString* files, const wxString& filespec = wxEmptyString, int flags = wxDIR_DEFAULT); /** - Start enumerating all files matching @e filespec (or all files if it is + Start enumerating all files matching @a filespec (or all files if it is empty) and @e flags, return @true on success. */ bool GetFirst(wxString* filename, const wxString& filespec = wxEmptyString, - int flags = wxDIR_DEFAULT); + 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). */ - wxString GetName(); + wxString GetName() const; /** Continue enumerating files which satisfy the criteria specified by the last call to GetFirst(). */ - bool GetNext(wxString* filename); + bool GetNext(wxString* filename) const; /** 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 be read, that file is added to the @c filesSkipped array, if not @NULL, and then skipped. @@ -210,16 +203,15 @@ public: then the returned value is not 100% accurate and, if the skipped files were big, it could be far from real size of the directory. - See also: wxFileName::GetHumanReadableSize, - wxGetDiskSpace + wxGetDiskSpace() */ static wxULongLong GetTotalSize(const wxString& dir, - wxArrayString* filesSkipped = @NULL); + wxArrayString* filesSkipped = NULL); /** - Returns @true if the directory contains any files matching the given - @e filespec. If @e filespec is empty, look for any files at all. In any + Returns @true if the directory contains any files matching the given + @e filespec. If @a filespec is empty, look for any files at all. In any case, even hidden files are taken into account. */ bool HasFiles(const wxString& filespec = wxEmptyString); @@ -232,10 +224,10 @@ public: bool HasSubDirs(const wxString& dirspec = wxEmptyString); /** - Returns @true if the directory was successfully opened by a previous call to + Returns @true if the directory was successfully opened by a previous call to Open(). */ - bool IsOpened(); + bool IsOpened() const; /** Open the directory for enumerating, returns @true on success @@ -245,24 +237,21 @@ public: /** Enumerate all files and directories under the given directory recursively - calling the element of the provided wxDirTraverser + calling the element of the provided wxDirTraverser object for each of them. - - More precisely, the function will really recurse into subdirectories if - @e flags contains @c wxDIR_DIRS flag. It will ignore the files (but + More precisely, the function will really recurse into subdirectories if + @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but still possibly recurse into subdirectories) if @c wxDIR_FILES flag is given. - For each found directory, @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. - The function returns the total number of files found or @c (size_t)-1 on error. - See also: GetAllFiles() */ size_t Traverse(wxDirTraverser& sink, const wxString& filespec = wxEmptyString, int flags = wxDIR_DEFAULT); }; +