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.
 222
 223         The returned string does not have the trailing path separator (slash or
 224         backslash).
 225
 226         Notice that in spite of this the last character of the returned string
 227         can still be the path separator if this directory is the root one.
 228         Because of this, don't append ::wxFILE_SEP_PATH to the returned value
 229         if you do need a slash-terminated directory name but use
 230         GetNameWithSep() instead to avoid having duplicate consecutive slashes.
 231     */
 232     wxString GetName() const;
 233
 234     /**
 235         Returns the name of the directory with the path separator appended.
 236
 237         The last character of the returned string is always ::wxFILE_SEP_PATH
 238         unless the string is empty, indicating that this directory is invalid.
 239
 240         @see GetName()
 241
 242         @since 2.9.4
 243      */
 244     wxString GetNameWithSep() const;
 245
 246     /**
 247         Continue enumerating files which satisfy the criteria specified by the
 248         last call to GetFirst().
 249     */
 250     bool GetNext(wxString* filename) const;
 251
 252     /**
 253         Returns the size (in bytes) of all files recursively found in @c dir or
 254         @c wxInvalidSize in case of error.
 255
 256         In case it happens that while traversing folders a file's size cannot
 257         be read, that file is added to the @a filesSkipped array, if not @NULL,
 258         and then skipped. This usually happens with some special folders which
 259         are locked by the operating system or by another process. Remember that
 260         when the size of @a filesSkipped is not zero, then the returned value
 261         is not 100% accurate and, if the skipped files were big, it could be
 262         far from real size of the directory.
 263
 264         @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
 265     */
 266     static wxULongLong GetTotalSize(const wxString& dir,
 267                                     wxArrayString* filesSkipped = NULL);
 268
 269     /**
 270         Returns @true if the directory contains any files matching the given
 271         @a filespec. If @a filespec is empty, look for any files at all. In any
 272         case, even hidden files are taken into account.
 273     */
 274     bool HasFiles(const wxString& filespec = wxEmptyString) const;
 275
 276     /**
 277         Returns @true if the directory contains any subdirectories (if a non
 278         empty @a filespec is given, only check for directories matching it).
 279         The hidden subdirectories are taken into account as well.
 280     */
 281     bool HasSubDirs(const wxString& dirspec = wxEmptyString) const;
 282
 283     /**
 284         Returns @true if the directory was successfully opened by a previous
 285         call to Open().
 286     */
 287     bool IsOpened() const;
 288
 289     /**
 290         Creates a directory.
 291
 292         This is just an alias for wxFileName::Mkdir(); refer to that function
 293         for more info.
 294     */
 295     static bool Make(const wxString &dir, int perm = wxS_DIR_DEFAULT,
 296                      int flags = 0);
 297
 298     /**
 299         Open the directory for enumerating, returns @true on success or @false
 300         if an error occurred.
 301     */
 302     bool Open(const wxString& dir);
 303
 304     /**
 305         Removes a directory.
 306
 307         This is just an alias for wxFileName::Rmdir(); refer to that function
 308         for more info.
 309     */
 310     static bool Remove(const wxString &dir, int flags = 0);
 311
 312     /**
 313         Enumerate all files and directories under the given directory.
 314
 315         If @a flags contains ::wxDIR_DIRS this enumeration is recursive, i.e.
 316         all the subdirectories of the given one and the files inside them will
 317         be traversed. Otherwise only the files in this directory itself are.
 318
 319         If @a flags doesn't contain ::wxDIR_FILES then only subdirectories are
 320         examined but not normal files. It doesn't make sense to not specify
 321         either ::wxDIR_DIRS or ::wxDIR_FILES and usually both of them should be
 322         specified, as is the case by default.
 323
 324         For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()"
 325         is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
 326         for every file. Depending on the return value, the enumeration may
 327         continue or stop. If entering a subdirectory fails, @ref
 328         wxDirTraverser::OnOpenError() "sink.OnOpenError()" is called.
 329
 330         The function returns the total number of files found or @c "(size_t)-1"
 331         on error.
 332
 333         See ::wxDirFlags for the full list of the possible flags.
 334
 335         @see GetAllFiles()
 336     */
 337     size_t Traverse(wxDirTraverser& sink,
 338                     const wxString& filespec = wxEmptyString,
 339                     int flags = wxDIR_DEFAULT) const;
 340 };
 341