interface/dir.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dir.h
   3 // Purpose:     documentation for wxDirTraverser class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDirTraverser
  11     @wxheader{dir.h}
  12
  13     wxDirTraverser is an abstract interface which must be implemented by objects
  14     passed to wxDir::Traverse function.
  15
  16     Example of use (this works almost like wxDir::GetAllFiles):
  17
  18     @code
  19     class wxDirTraverserSimple : public wxDirTraverser
  20         {
  21         public:
  22             wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
  23
  24             virtual wxDirTraverseResult OnFile(const wxString& filename)
  25             {
  26                 m_files.Add(filename);
  27                 return wxDIR_CONTINUE;
  28             }
  29
  30             virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
  31             {
  32                 return wxDIR_CONTINUE;
  33             }
  34
  35         private:
  36             wxArrayString& m_files;
  37         };
  38
  39         // get the names of all files in the array
  40         wxArrayString files;
  41         wxDirTraverserSimple traverser(files);
  42
  43         wxDir dir(dirname);
  44         dir.Traverse(traverser);
  45     @endcode
  46
  47     @library{wxbase}
  48     @category{file}
  49 */
  50 class wxDirTraverser
  51 {
  52 public:
  53     /**
  54         This function is called for each directory. It may return @c wxSIR_STOP
  55         to abort traversing completely, @c wxDIR_IGNORE to skip this directory but
  56         continue with others or @c wxDIR_CONTINUE to enumerate all files and
  57         subdirectories in this directory.
  58         This is a pure virtual function and must be implemented in the derived class.
  59     */
  60     virtual wxDirTraverseResult OnDir(const wxString& dirname);
  61
  62     /**
  63         This function is called for each file. It may return @c wxDIR_STOP to abort
  64         traversing (for example, if the file being searched is found) or
  65         @c wxDIR_CONTINUE to proceed.
  66         This is a pure virtual function and must be implemented in the derived class.
  67     */
  68     virtual wxDirTraverseResult OnFile(const wxString& filename);
  69
  70     /**
  71         This function is called for each directory which we failed to open for
  72         enumerating. It may return @c wxSIR_STOP to abort traversing completely,
  73         @c wxDIR_IGNORE to skip this directory but continue with others or
  74         @c wxDIR_CONTINUE to retry opening this directory once again.
  75         The base class version always returns @c wxDIR_IGNORE.
  76     */
  77     virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
  78 };
  79
  80
  81 /**
  82     @class wxDir
  83     @wxheader{dir.h}
  84
  85     wxDir is a portable equivalent of Unix open/read/closedir functions which
  86     allow enumerating of the files in a directory. wxDir allows to enumerate files
  87     as well as directories.
  88
  89     wxDir also provides a flexible way to enumerate files recursively using
  90     wxDir::Traverse or a simpler
  91     wxDir::GetAllFiles function.
  92
  93     Example of use:
  94
  95     @code
  96     wxDir dir(wxGetCwd());
  97
  98         if ( !dir.IsOpened() )
  99         {
 100             // deal with the error here - wxDir would already log an error message
 101             // explaining the exact reason of the failure
 102             return;
 103         }
 104
 105         puts("Enumerating object files in current directory:");
 106
 107         wxString filename;
 108
 109         bool cont = dir.GetFirst(, filespec, flags);
 110         while ( cont )
 111         {
 112             printf("%s\n", filename.c_str());
 113
 114             cont = dir.GetNext();
 115         }
 116     @endcode
 117
 118     @library{wxbase}
 119     @category{file}
 120 */
 121 class wxDir
 122 {
 123 public:
 124     //@{
 125     /**
 126         Opens the directory for enumeration, use IsOpened()
 127         to test for errors.
 128     */
 129     wxDir();
 130     wxDir(const wxString& dir);
 131     //@}
 132
 133     /**
 134         Destructor cleans up the associated resources. It is not virtual and so this
 135         class is not meant to be used polymorphically.
 136     */
 137     ~wxDir();
 138
 139     /**
 140         Test for existence of a directory with the given name
 141     */
 142     static bool Exists(const wxString& dir);
 143
 144     /**
 145         The function returns the path of the first file matching the given @e filespec
 146         or an empty string if there are no files matching it.
 147         The @a flags parameter may or may not include @c wxDIR_FILES, the
 148         function always behaves as if it were specified. By default, @a flags
 149         includes @c wxDIR_DIRS and so the function recurses into the subdirectories
 150         but if this flag is not specified, the function restricts the search only to
 151         the directory @a dirname itself.
 152         See also: Traverse()
 153     */
 154     static wxString FindFirst(const wxString& dirname,
 155                               const wxString& filespec,
 156                               int flags = wxDIR_DEFAULT);
 157
 158     /**
 159         The function appends the names of all the files under directory @a dirname
 160         to the array @a files (note that its old content is preserved). Only files
 161         matching the @a filespec are taken, with empty spec matching all the files.
 162         The @a flags parameter should always include @c wxDIR_FILES or the array
 163         would be unchanged and should include @c wxDIR_DIRS flag to recurse into
 164         subdirectories (both flags are included in the value by default).
 165         See also: Traverse()
 166     */
 167     static size_t GetAllFiles(const wxString& dirname,
 168                               wxArrayString* files,
 169                               const wxString& filespec = wxEmptyString,
 170                               int flags = wxDIR_DEFAULT);
 171
 172     /**
 173         Start enumerating all files matching @a filespec (or all files if it is
 174         empty) and @e flags, return @true on success.
 175     */
 176     bool GetFirst(wxString* filename,
 177                   const wxString& filespec = wxEmptyString,
 178                   int flags = wxDIR_DEFAULT) const;
 179
 180     /**
 181         Returns the name of the directory itself. The returned string does not have the
 182         trailing path separator (slash or backslash).
 183     */
 184     wxString GetName() const;
 185
 186     /**
 187         Continue enumerating files which satisfy the criteria specified by the last
 188         call to GetFirst().
 189     */
 190     bool GetNext(wxString* filename) const;
 191
 192     /**
 193         Returns the size (in bytes) of all files recursively found in @c dir or
 194         @c wxInvalidSize in case of error.
 195         In case it happens that while traversing folders a file's size can not be read,
 196         that file is added to the @c filesSkipped array, if not @NULL, and then
 197         skipped.
 198         This usually happens with some special folders which are locked by the
 199         operating system
 200         or by another process. Remember that when @c filesSkipped-GetCount() is not
 201         zero,
 202         then the returned value is not 100% accurate and, if the skipped files were
 203         big, it could be
 204         far from real size of the directory.
 205         See also: wxFileName::GetHumanReadableSize,
 206         wxGetDiskSpace
 207     */
 208     static wxULongLong GetTotalSize(const wxString& dir,
 209                                     wxArrayString* filesSkipped = NULL);
 210
 211     /**
 212         Returns @true if the directory contains any files matching the given
 213         @e filespec. If @a filespec is empty, look for any files at all. In any
 214         case, even hidden files are taken into account.
 215     */
 216     bool HasFiles(const wxString& filespec = wxEmptyString);
 217
 218     /**
 219         Returns @true if the directory contains any subdirectories (if a non
 220         empty @e filespec is given, only check for directories matching it).
 221         The hidden subdirectories are taken into account as well.
 222     */
 223     bool HasSubDirs(const wxString& dirspec = wxEmptyString);
 224
 225     /**
 226         Returns @true if the directory was successfully opened by a previous call to
 227         Open().
 228     */
 229     bool IsOpened() const;
 230
 231     /**
 232         Open the directory for enumerating, returns @true on success
 233         or @false if an error occurred.
 234     */
 235     bool Open(const wxString& dir);
 236
 237     /**
 238         Enumerate all files and directories under the given directory recursively
 239         calling the element of the provided wxDirTraverser
 240         object for each of them.
 241         More precisely, the function will really recurse into subdirectories if
 242         @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but
 243         still possibly recurse into subdirectories) if @c wxDIR_FILES flag is
 244         given.
 245         For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called
 246         and @ref wxDirTraverser::onfile sink.OnFile is called for every file.
 247         Depending on the return value, the enumeration may continue or stop.
 248         The function returns the total number of files found or @c (size_t)-1 on
 249         error.
 250         See also: GetAllFiles()
 251     */
 252     size_t Traverse(wxDirTraverser& sink,
 253                     const wxString& filespec = wxEmptyString,
 254                     int flags = wxDIR_DEFAULT);
 255 };