interface/wx/dir.h

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