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