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 by calling Close().
 164
 165         It is not virtual and so this class is not meant to be used
 166         polymorphically.
 167     */
 168     ~wxDir();
 169
 170     /**
 171         Close the directory.
 172
 173         The object can't be used after closing it, but Open() may be called
 174         again to reopen it later.
 175
 176         @since 2.9.5
 177     */
 178     void Close();
 179
 180     /**
 181         Test for existence of a directory with the given name.
 182     */
 183     static bool Exists(const wxString& dir);
 184
 185     /**
 186         The function returns the path of the first file matching the given
 187         @a filespec or an empty string if there are no files matching it.
 188
 189         The @a flags parameter may or may not include ::wxDIR_FILES, the
 190         function always behaves as if it were specified. By default, @a flags
 191         includes ::wxDIR_DIRS and so the function recurses into the
 192         subdirectories but if this flag is not specified, the function
 193         restricts the search only to the directory @a dirname itself.
 194         See ::wxDirFlags for the list of the possible flags.
 195
 196         @see Traverse()
 197     */
 198     static wxString FindFirst(const wxString& dirname,
 199                               const wxString& filespec,
 200                               int flags = wxDIR_DEFAULT);
 201
 202     /**
 203         The function appends the names of all the files under directory
 204         @a dirname to the array @a files (note that its old content is
 205         preserved). Only files matching the @a filespec are taken, with empty
 206         spec matching all the files.
 207
 208         The @a flags parameter should always include ::wxDIR_FILES or the array
 209         would be unchanged and should include ::wxDIR_DIRS flag to recurse into
 210         subdirectories (both flags are included in the value by default).
 211         See ::wxDirFlags for the list of the possible flags.
 212
 213         @return Returns the total number of files found while traversing
 214                 the directory @a dirname (i.e. the number of entries appended
 215                 to the @a files array).
 216
 217         @see Traverse()
 218     */
 219     static size_t GetAllFiles(const wxString& dirname, wxArrayString* files,
 220                               const wxString& filespec = wxEmptyString,
 221                               int flags = wxDIR_DEFAULT);
 222
 223     /**
 224         Start enumerating all files matching @a filespec (or all files if it is
 225         empty) and @e flags, return @true on success.
 226         See ::wxDirFlags for the list of the possible flags.
 227     */
 228     bool GetFirst(wxString* filename,
 229                   const wxString& filespec = wxEmptyString,
 230                   int flags = wxDIR_DEFAULT) const;
 231
 232     /**
 233         Returns the name of the directory itself.
 234
 235         The returned string does not have the trailing path separator (slash or
 236         backslash).
 237
 238         Notice that in spite of this the last character of the returned string
 239         can still be the path separator if this directory is the root one.
 240         Because of this, don't append ::wxFILE_SEP_PATH to the returned value
 241         if you do need a slash-terminated directory name but use
 242         GetNameWithSep() instead to avoid having duplicate consecutive slashes.
 243     */
 244     wxString GetName() const;
 245
 246     /**
 247         Returns the name of the directory with the path separator appended.
 248
 249         The last character of the returned string is always ::wxFILE_SEP_PATH
 250         unless the string is empty, indicating that this directory is invalid.
 251
 252         @see GetName()
 253
 254         @since 2.9.4
 255      */
 256     wxString GetNameWithSep() const;
 257
 258     /**
 259         Continue enumerating files which satisfy the criteria specified by the
 260         last call to GetFirst().
 261     */
 262     bool GetNext(wxString* filename) const;
 263
 264     /**
 265         Returns the size (in bytes) of all files recursively found in @c dir or
 266         @c wxInvalidSize in case of error.
 267
 268         In case it happens that while traversing folders a file's size cannot
 269         be read, that file is added to the @a filesSkipped array, if not @NULL,
 270         and then skipped. This usually happens with some special folders which
 271         are locked by the operating system or by another process. Remember that
 272         when the size of @a filesSkipped is not zero, then the returned value
 273         is not 100% accurate and, if the skipped files were big, it could be
 274         far from real size of the directory.
 275
 276         @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
 277     */
 278     static wxULongLong GetTotalSize(const wxString& dir,
 279                                     wxArrayString* filesSkipped = NULL);
 280
 281     /**
 282         Returns @true if the directory contains any files matching the given
 283         @a filespec. If @a filespec is empty, look for any files at all. In any
 284         case, even hidden files are taken into account.
 285     */
 286     bool HasFiles(const wxString& filespec = wxEmptyString) const;
 287
 288     /**
 289         Returns @true if the directory contains any subdirectories (if a non
 290         empty @a filespec is given, only check for directories matching it).
 291         The hidden subdirectories are taken into account as well.
 292     */
 293     bool HasSubDirs(const wxString& dirspec = wxEmptyString) const;
 294
 295     /**
 296         Returns @true if the directory was successfully opened by a previous
 297         call to Open().
 298     */
 299     bool IsOpened() const;
 300
 301     /**
 302         Creates a directory.
 303
 304         This is just an alias for wxFileName::Mkdir(); refer to that function
 305         for more info.
 306     */
 307     static bool Make(const wxString &dir, int perm = wxS_DIR_DEFAULT,
 308                      int flags = 0);
 309
 310     /**
 311         Open the directory for enumerating, returns @true on success or @false
 312         if an error occurred.
 313     */
 314     bool Open(const wxString& dir);
 315
 316     /**
 317         Removes a directory.
 318
 319         This is just an alias for wxFileName::Rmdir(); refer to that function
 320         for more info.
 321     */
 322     static bool Remove(const wxString &dir, int flags = 0);
 323
 324     /**
 325         Enumerate all files and directories under the given directory.
 326
 327         If @a flags contains ::wxDIR_DIRS this enumeration is recursive, i.e.
 328         all the subdirectories of the given one and the files inside them will
 329         be traversed. Otherwise only the files in this directory itself are.
 330
 331         If @a flags doesn't contain ::wxDIR_FILES then only subdirectories are
 332         examined but not normal files. It doesn't make sense to not specify
 333         either ::wxDIR_DIRS or ::wxDIR_FILES and usually both of them should be
 334         specified, as is the case by default.
 335
 336         For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()"
 337         is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
 338         for every file. Depending on the return value, the enumeration may
 339         continue or stop. If entering a subdirectory fails, @ref
 340         wxDirTraverser::OnOpenError() "sink.OnOpenError()" is called.
 341
 342         The function returns the total number of files found or @c "(size_t)-1"
 343         on error.
 344
 345         See ::wxDirFlags for the full list of the possible flags.
 346
 347         @see GetAllFiles()
 348     */
 349     size_t Traverse(wxDirTraverser& sink,
 350                     const wxString& filespec = wxEmptyString,
 351                     int flags = wxDIR_DEFAULT) const;
 352 };
 353