interface/dir.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dir.h
   3 // Purpose:     interface of wxDirTraverser
   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 wxDIR_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 wxDIR_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 /**
  83     @class wxDir
  84     @wxheader{dir.h}
  85
  86     wxDir is a portable equivalent of Unix open/read/closedir functions which
  87     allow enumerating of the files in a directory. wxDir allows to enumerate files
  88     as well as directories.
  89
  90     wxDir also provides a flexible way to enumerate files recursively using
  91     wxDir::Traverse or a simpler
  92     wxDir::GetAllFiles function.
  93
  94     Example of use:
  95
  96     @code
  97     wxDir dir(wxGetCwd());
  98
  99         if ( !dir.IsOpened() )
 100         {
 101             // deal with the error here - wxDir would already log an error message
 102             // explaining the exact reason of the failure
 103             return;
 104         }
 105
 106         puts("Enumerating object files in current directory:");
 107
 108         wxString filename;
 109
 110         bool cont = dir.GetFirst(, filespec, flags);
 111         while ( cont )
 112         {
 113             printf("%s\n", filename.c_str());
 114
 115             cont = dir.GetNext();
 116         }
 117     @endcode
 118
 119     @library{wxbase}
 120     @category{file}
 121 */
 122 class wxDir
 123 {
 124 public:
 125     //@{
 126     /**
 127         Opens the directory for enumeration, use IsOpened()
 128         to test for errors.
 129     */
 130     wxDir();
 131     wxDir(const wxString& dir);
 132     //@}
 133
 134     /**
 135         Destructor cleans up the associated resources. It is not virtual and so this
 136         class is not meant to be used polymorphically.
 137     */
 138     ~wxDir();
 139
 140     /**
 141         Test for existence of a directory with the given name
 142     */
 143     static bool Exists(const wxString& dir);
 144
 145     /**
 146         The function returns the path of the first file matching the given @e filespec
 147         or an empty string if there are no files matching it.
 148         The @a flags parameter may or may not include @c wxDIR_FILES, the
 149         function always behaves as if it were specified. By default, @a flags
 150         includes @c wxDIR_DIRS and so the function recurses into the subdirectories
 151         but if this flag is not specified, the function restricts the search only to
 152         the directory @a dirname itself.
 153         See also: Traverse()
 154     */
 155     static wxString FindFirst(const wxString& dirname,
 156                               const wxString& filespec,
 157                               int flags = wxDIR_DEFAULT);
 158
 159     /**
 160         The function appends the names of all the files under directory @a dirname
 161         to the array @a files (note that its old content is preserved). Only files
 162         matching the @a filespec are taken, with empty spec matching all the files.
 163         The @a flags parameter should always include @c wxDIR_FILES or the array
 164         would be unchanged and should include @c wxDIR_DIRS flag to recurse into
 165         subdirectories (both flags are included in the value by default).
 166         See also: Traverse()
 167     */
 168     static size_t GetAllFiles(const wxString& dirname,
 169                               wxArrayString* files,
 170                               const wxString& filespec = wxEmptyString,
 171                               int flags = wxDIR_DEFAULT);
 172
 173     /**
 174         Start enumerating all files matching @a filespec (or all files if it is
 175         empty) and @e flags, return @true on success.
 176     */
 177     bool GetFirst(wxString* filename,
 178                   const wxString& filespec = wxEmptyString,
 179                   int flags = wxDIR_DEFAULT) const;
 180
 181     /**
 182         Returns the name of the directory itself. The returned string does not have the
 183         trailing path separator (slash or backslash).
 184     */
 185     wxString GetName() const;
 186
 187     /**
 188         Continue enumerating files which satisfy the criteria specified by the last
 189         call to GetFirst().
 190     */
 191     bool GetNext(wxString* filename) const;
 192
 193     /**
 194         Returns the size (in bytes) of all files recursively found in @c dir or
 195         @c wxInvalidSize in case of error.
 196         In case it happens that while traversing folders a file's size can not be read,
 197         that file is added to the @c filesSkipped array, if not @NULL, and then
 198         skipped.
 199         This usually happens with some special folders which are locked by the
 200         operating system
 201         or by another process. Remember that when @c filesSkipped-GetCount() is not
 202         zero,
 203         then the returned value is not 100% accurate and, if the skipped files were
 204         big, it could be
 205         far from real size of the directory.
 206         See also: wxFileName::GetHumanReadableSize,
 207         wxGetDiskSpace()
 208     */
 209     static wxULongLong GetTotalSize(const wxString& dir,
 210                                     wxArrayString* filesSkipped = NULL);
 211
 212     /**
 213         Returns @true if the directory contains any files matching the given
 214         @e filespec. If @a filespec is empty, look for any files at all. In any
 215         case, even hidden files are taken into account.
 216     */
 217     bool HasFiles(const wxString& filespec = wxEmptyString);
 218
 219     /**
 220         Returns @true if the directory contains any subdirectories (if a non
 221         empty @e filespec is given, only check for directories matching it).
 222         The hidden subdirectories are taken into account as well.
 223     */
 224     bool HasSubDirs(const wxString& dirspec = wxEmptyString);
 225
 226     /**
 227         Returns @true if the directory was successfully opened by a previous call to
 228         Open().
 229     */
 230     bool IsOpened() const;
 231
 232     /**
 233         Open the directory for enumerating, returns @true on success
 234         or @false if an error occurred.
 235     */
 236     bool Open(const wxString& dir);
 237
 238     /**
 239         Enumerate all files and directories under the given directory recursively
 240         calling the element of the provided wxDirTraverser
 241         object for each of them.
 242         More precisely, the function will really recurse into subdirectories if
 243         @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but
 244         still possibly recurse into subdirectories) if @c wxDIR_FILES flag is
 245         given.
 246         For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called
 247         and @ref wxDirTraverser::onfile sink.OnFile is called for every file.
 248         Depending on the return value, the enumeration may continue or stop.
 249         The function returns the total number of files found or @c (size_t)-1 on
 250         error.
 251         See also: GetAllFiles()
 252     */
 253     size_t Traverse(wxDirTraverser& sink,
 254                     const wxString& filespec = wxEmptyString,
 255                     int flags = wxDIR_DEFAULT);
 256 };
 257