interface/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 license
   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     @wxheader{dir.h}
  22
  23     wxDirTraverser is an abstract interface which must be implemented by
  24     objects passed to wxDir::Traverse() function.
  25
  26     Example of use (this works almost like wxDir::GetAllFiles()):
  27
  28     @code
  29     class wxDirTraverserSimple : public wxDirTraverser
  30     {
  31     public:
  32         wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
  33
  34         virtual wxDirTraverseResult OnFile(const wxString& filename)
  35         {
  36             m_files.Add(filename);
  37             return wxDIR_CONTINUE;
  38         }
  39
  40         virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
  41         {
  42             return wxDIR_CONTINUE;
  43         }
  44
  45     private:
  46         wxArrayString& m_files;
  47     };
  48
  49     // get the names of all files in the array
  50     wxArrayString files;
  51     wxDirTraverserSimple traverser(files);
  52
  53     wxDir dir(dirname);
  54     dir.Traverse(traverser);
  55     @endcode
  56
  57     @library{wxbase}
  58     @category{file}
  59 */
  60 class wxDirTraverser
  61 {
  62 public:
  63     /**
  64         This function is called for each directory. It may return ::wxDIR_STOP
  65         to abort traversing completely, ::wxDIR_IGNORE to skip this directory
  66         but continue with others or ::wxDIR_CONTINUE to enumerate all files and
  67         subdirectories in this directory.
  68
  69         This is a pure virtual function and must be implemented in the derived
  70         class.
  71     */
  72     virtual wxDirTraverseResult OnDir(const wxString& dirname);
  73
  74     /**
  75         This function is called for each file. It may return ::wxDIR_STOP to
  76         abort traversing (for example, if the file being searched is found) or
  77         ::wxDIR_CONTINUE to proceed.
  78
  79         This is a pure virtual function and must be implemented in the derived
  80         class.
  81     */
  82     virtual wxDirTraverseResult OnFile(const wxString& filename);
  83
  84     /**
  85         This function is called for each directory which we failed to open for
  86         enumerating. It may return ::wxDIR_STOP to abort traversing completely,
  87         ::wxDIR_IGNORE to skip this directory but continue with others or
  88         ::wxDIR_CONTINUE to retry opening this directory once again.
  89
  90         The base class version always returns ::wxDIR_IGNORE.
  91     */
  92     virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
  93 };
  94
  95
  96
  97 /**
  98     These flags define what kind of filenames are included in the list of files
  99     enumerated by wxDir::GetFirst() and wxDir::GetNext().
 100 */
 101 enum
 102 {
 103     wxDIR_FILES     = 0x0001,   ///< Includes files.
 104     wxDIR_DIRS      = 0x0002,   ///< Includes directories.
 105     wxDIR_HIDDEN    = 0x0004,   ///< Includes hidden files.
 106     wxDIR_DOTDOT    = 0x0008,   ///< Includes "." and "..".
 107
 108     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
 109 };
 110
 111 /**
 112     @class wxDir
 113     @wxheader{dir.h}
 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
 183         @see Traverse()
 184     */
 185     static wxString FindFirst(const wxString& dirname,
 186                               const wxString& filespec,
 187                               int flags = wxDIR_DEFAULT);
 188
 189     /**
 190         The function appends the names of all the files under directory
 191         @a dirname to the array @a files (note that its old content is
 192         preserved). Only files matching the @a filespec are taken, with empty
 193         spec matching all the files.
 194
 195         The @a flags parameter should always include ::wxDIR_FILES or the array
 196         would be unchanged and should include ::wxDIR_DIRS flag to recurse into
 197         subdirectories (both flags are included in the value by default).
 198
 199         @see Traverse()
 200     */
 201     static size_t GetAllFiles(const wxString& dirname, wxArrayString* files,
 202                               const wxString& filespec = wxEmptyString,
 203                               int flags = wxDIR_DEFAULT);
 204
 205     /**
 206         Start enumerating all files matching @a filespec (or all files if it is
 207         empty) and @e flags, return @true on success.
 208     */
 209     bool GetFirst(wxString* filename,
 210                   const wxString& filespec = wxEmptyString,
 211                   int flags = wxDIR_DEFAULT) const;
 212
 213     /**
 214         Returns the name of the directory itself. The returned string does not
 215         have the trailing path separator (slash or backslash).
 216     */
 217     wxString GetName() const;
 218
 219     /**
 220         Continue enumerating files which satisfy the criteria specified by the
 221         last call to GetFirst().
 222     */
 223     bool GetNext(wxString* filename) const;
 224
 225     /**
 226         Returns the size (in bytes) of all files recursively found in @c dir or
 227         @c wxInvalidSize in case of error.
 228
 229         In case it happens that while traversing folders a file's size can not
 230         be read, that file is added to the @a filesSkipped array, if not @NULL,
 231         and then skipped. This usually happens with some special folders which
 232         are locked by the operating system or by another process. Remember that
 233         when the size of @a filesSkipped is not zero, then the returned value
 234         is not 100% accurate and, if the skipped files were big, it could be
 235         far from real size of the directory.
 236
 237         @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
 238     */
 239     static wxULongLong GetTotalSize(const wxString& dir,
 240                                     wxArrayString* filesSkipped = NULL);
 241
 242     /**
 243         Returns @true if the directory contains any files matching the given
 244         @a filespec. If @a filespec is empty, look for any files at all. In any
 245         case, even hidden files are taken into account.
 246     */
 247     bool HasFiles(const wxString& filespec = wxEmptyString) const;
 248
 249     /**
 250         Returns @true if the directory contains any subdirectories (if a non
 251         empty @a filespec is given, only check for directories matching it).
 252         The hidden subdirectories are taken into account as well.
 253     */
 254     bool HasSubDirs(const wxString& dirspec = wxEmptyString) const;
 255
 256     /**
 257         Returns @true if the directory was successfully opened by a previous
 258         call to Open().
 259     */
 260     bool IsOpened() const;
 261
 262     /**
 263         Open the directory for enumerating, returns @true on success or @false
 264         if an error occurred.
 265     */
 266     bool Open(const wxString& dir);
 267
 268     /**
 269         Enumerate all files and directories under the given directory
 270         recursively calling the element of the provided wxDirTraverser object
 271         for each of them.
 272
 273         More precisely, the function will really recurse into subdirectories if
 274         @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but
 275         still possibly recurse into subdirectories) if ::wxDIR_FILES flag is
 276         given.
 277
 278         For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()"
 279         is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
 280         for every file. Depending on the return value, the enumeration may
 281         continue or stop.
 282
 283         The function returns the total number of files found or @c "(size_t)-1"
 284         on error.
 285
 286         @see GetAllFiles()
 287     */
 288     size_t Traverse(wxDirTraverser& sink,
 289                     const wxString& filespec = wxEmptyString,
 290                     int flags = wxDIR_DEFAULT);
 291 };
 292