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);
  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);
  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
 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
 181         @see Traverse()
 182     */
 183     static wxString FindFirst(const wxString& dirname,
 184                               const wxString& filespec,
 185                               int flags = wxDIR_DEFAULT);
 186
 187     /**
 188         The function appends the names of all the files under directory
 189         @a dirname to the array @a files (note that its old content is
 190         preserved). Only files matching the @a filespec are taken, with empty
 191         spec matching all the files.
 192
 193         The @a flags parameter should always include ::wxDIR_FILES or the array
 194         would be unchanged and should include ::wxDIR_DIRS flag to recurse into
 195         subdirectories (both flags are included in the value by default).
 196
 197         @see Traverse()
 198     */
 199     static size_t GetAllFiles(const wxString& dirname, wxArrayString* files,
 200                               const wxString& filespec = wxEmptyString,
 201                               int flags = wxDIR_DEFAULT);
 202
 203     /**
 204         Start enumerating all files matching @a filespec (or all files if it is
 205         empty) and @e flags, return @true on success.
 206     */
 207     bool GetFirst(wxString* filename,
 208                   const wxString& filespec = wxEmptyString,
 209                   int flags = wxDIR_DEFAULT) const;
 210
 211     /**
 212         Returns the name of the directory itself. The returned string does not
 213         have the trailing path separator (slash or backslash).
 214     */
 215     wxString GetName() const;
 216
 217     /**
 218         Continue enumerating files which satisfy the criteria specified by the
 219         last call to GetFirst().
 220     */
 221     bool GetNext(wxString* filename) const;
 222
 223     /**
 224         Returns the size (in bytes) of all files recursively found in @c dir or
 225         @c wxInvalidSize in case of error.
 226
 227         In case it happens that while traversing folders a file's size can not
 228         be read, that file is added to the @a filesSkipped array, if not @NULL,
 229         and then skipped. This usually happens with some special folders which
 230         are locked by the operating system or by another process. Remember that
 231         when the size of @a filesSkipped is not zero, then the returned value
 232         is not 100% accurate and, if the skipped files were big, it could be
 233         far from real size of the directory.
 234
 235         @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
 236     */
 237     static wxULongLong GetTotalSize(const wxString& dir,
 238                                     wxArrayString* filesSkipped = NULL);
 239
 240     /**
 241         Returns @true if the directory contains any files matching the given
 242         @a filespec. If @a filespec is empty, look for any files at all. In any
 243         case, even hidden files are taken into account.
 244     */
 245     bool HasFiles(const wxString& filespec = wxEmptyString) const;
 246
 247     /**
 248         Returns @true if the directory contains any subdirectories (if a non
 249         empty @a filespec is given, only check for directories matching it).
 250         The hidden subdirectories are taken into account as well.
 251     */
 252     bool HasSubDirs(const wxString& dirspec = wxEmptyString) const;
 253
 254     /**
 255         Returns @true if the directory was successfully opened by a previous
 256         call to Open().
 257     */
 258     bool IsOpened() const;
 259
 260     /**
 261         Open the directory for enumerating, returns @true on success or @false
 262         if an error occurred.
 263     */
 264     bool Open(const wxString& dir);
 265
 266     /**
 267         Enumerate all files and directories under the given directory
 268         recursively calling the element of the provided wxDirTraverser object
 269         for each of them.
 270
 271         More precisely, the function will really recurse into subdirectories if
 272         @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but
 273         still possibly recurse into subdirectories) if ::wxDIR_FILES flag is
 274         given.
 275
 276         For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()"
 277         is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
 278         for every file. Depending on the return value, the enumeration may
 279         continue or stop.
 280
 281         The function returns the total number of files found or @c "(size_t)-1"
 282         on error.
 283
 284         @see GetAllFiles()
 285     */
 286     size_t Traverse(wxDirTraverser& sink,
 287                     const wxString& filespec = wxEmptyString,
 288                     int flags = wxDIR_DEFAULT);
 289 };
 290