interface/dir.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dir.h
   3 // Purpose:     documentation for wxDirTraverser class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDirTraverser
  11     @wxheader{dir.h}
  12
  13     wxDirTraverser is an abstract interface which must be implemented by objects
  14     passed to wxDir::Traverse function.
  15
  16     Example of use (this works almost like wxDir::GetAllFiles):
  17
  18     @code
  19     class wxDirTraverserSimple : public wxDirTraverser
  20         {
  21         public:
  22             wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
  23
  24             virtual wxDirTraverseResult OnFile(const wxString& filename)
  25             {
  26                 m_files.Add(filename);
  27                 return wxDIR_CONTINUE;
  28             }
  29
  30             virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
  31             {
  32                 return wxDIR_CONTINUE;
  33             }
  34
  35         private:
  36             wxArrayString& m_files;
  37         };
  38
  39         // get the names of all files in the array
  40         wxArrayString files;
  41         wxDirTraverserSimple traverser(files);
  42
  43         wxDir dir(dirname);
  44         dir.Traverse(traverser);
  45     @endcode
  46
  47     @library{wxbase}
  48     @category{file}
  49 */
  50 class wxDirTraverser
  51 {
  52 public:
  53     /**
  54         This function is called for each directory. It may return @c wxSIR_STOP
  55         to abort traversing completely, @c wxDIR_IGNORE to skip this directory but
  56         continue with others or @c wxDIR_CONTINUE to enumerate all files and
  57         subdirectories in this directory.
  58
  59         This is a pure virtual function and must be implemented in the derived class.
  60     */
  61     virtual wxDirTraverseResult OnDir(const wxString& dirname);
  62
  63     /**
  64         This function is called for each file. It may return @c wxDIR_STOP to abort
  65         traversing (for example, if the file being searched is found) or
  66         @c wxDIR_CONTINUE to proceed.
  67
  68         This is a pure virtual function and must be implemented in the derived class.
  69     */
  70     virtual wxDirTraverseResult OnFile(const wxString& filename);
  71
  72     /**
  73         This function is called for each directory which we failed to open for
  74         enumerating. It may return @c wxSIR_STOP to abort traversing completely,
  75         @c wxDIR_IGNORE to skip this directory but continue with others or
  76         @c wxDIR_CONTINUE to retry opening this directory once again.
  77
  78         The base class version always returns @c wxDIR_IGNORE.
  79     */
  80     virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
  81 };
  82
  83
  84 /**
  85     @class wxDir
  86     @wxheader{dir.h}
  87
  88     wxDir is a portable equivalent of Unix open/read/closedir functions which
  89     allow enumerating of the files in a directory. wxDir allows to enumerate files
  90     as well as directories.
  91
  92     wxDir also provides a flexible way to enumerate files recursively using
  93     wxDir::Traverse or a simpler
  94     wxDir::GetAllFiles function.
  95
  96     Example of use:
  97
  98     @code
  99     wxDir dir(wxGetCwd());
 100
 101         if ( !dir.IsOpened() )
 102         {
 103             // deal with the error here - wxDir would already log an error message
 104             // explaining the exact reason of the failure
 105             return;
 106         }
 107
 108         puts("Enumerating object files in current directory:");
 109
 110         wxString filename;
 111
 112         bool cont = dir.GetFirst(, filespec, flags);
 113         while ( cont )
 114         {
 115             printf("%s\n", filename.c_str());
 116
 117             cont = dir.GetNext();
 118         }
 119     @endcode
 120
 121     @library{wxbase}
 122     @category{file}
 123 */
 124 class wxDir
 125 {
 126 public:
 127     //@{
 128     /**
 129         Opens the directory for enumeration, use IsOpened()
 130         to test for errors.
 131     */
 132     wxDir();
 133     wxDir(const wxString& dir);
 134     //@}
 135
 136     /**
 137         Destructor cleans up the associated resources. It is not virtual and so this
 138         class is not meant to be used polymorphically.
 139     */
 140     ~wxDir();
 141
 142     /**
 143         Test for existence of a directory with the given name
 144     */
 145     static bool Exists(const wxString& dir);
 146
 147     /**
 148         The function returns the path of the first file matching the given @e filespec
 149         or an empty string if there are no files matching it.
 150
 151         The @e flags parameter may or may not include @c wxDIR_FILES, the
 152         function always behaves as if it were specified. By default, @e flags
 153         includes @c wxDIR_DIRS and so the function recurses into the subdirectories
 154         but if this flag is not specified, the function restricts the search only to
 155         the directory @e dirname itself.
 156
 157         See also: Traverse()
 158     */
 159     static wxString FindFirst(const wxString& dirname,
 160                               const wxString& filespec,
 161                               int flags = wxDIR_DEFAULT);
 162
 163     /**
 164         The function appends the names of all the files under directory @e dirname
 165         to the array @e files (note that its old content is preserved). Only files
 166         matching the @e filespec are taken, with empty spec matching all the files.
 167
 168         The @e flags parameter should always include @c wxDIR_FILES or the array
 169         would be unchanged and should include @c wxDIR_DIRS flag to recurse into
 170         subdirectories (both flags are included in the value by default).
 171
 172         See also: Traverse()
 173     */
 174     static size_t GetAllFiles(const wxString& dirname,
 175                               wxArrayString * files,
 176                               const wxString& filespec = wxEmptyString,
 177                               int flags = wxDIR_DEFAULT);
 178
 179     /**
 180         Start enumerating all files matching @e filespec (or all files if it is
 181         empty) and @e flags, return @true on success.
 182     */
 183     bool GetFirst(wxString* filename,
 184                   const wxString& filespec = wxEmptyString,
 185                   int flags = wxDIR_DEFAULT);
 186
 187     /**
 188         Returns the name of the directory itself. The returned string does not have the
 189         trailing path separator (slash or backslash).
 190     */
 191     wxString GetName();
 192
 193     /**
 194         Continue enumerating files which satisfy the criteria specified by the last
 195         call to GetFirst().
 196     */
 197     bool GetNext(wxString* filename);
 198
 199     /**
 200         Returns the size (in bytes) of all files recursively found in @c dir or
 201         @c wxInvalidSize in case of error.
 202
 203         In case it happens that while traversing folders a file's size can not be read,
 204         that file is added to the @c filesSkipped array, if not @NULL, and then
 205         skipped.
 206         This usually happens with some special folders which are locked by the
 207         operating system
 208         or by another process. Remember that when @c filesSkipped-GetCount() is not
 209         zero,
 210         then the returned value is not 100% accurate and, if the skipped files were
 211         big, it could be
 212         far from real size of the directory.
 213
 214         See also: wxFileName::GetHumanReadableSize,
 215         wxGetDiskSpace
 216     */
 217     static wxULongLong GetTotalSize(const wxString& dir,
 218                                     wxArrayString* filesSkipped = @NULL);
 219
 220     /**
 221         Returns @true if the directory contains any files matching the given
 222         @e filespec. If @e filespec is empty, look for any files at all. In any
 223         case, even hidden files are taken into account.
 224     */
 225     bool HasFiles(const wxString& filespec = wxEmptyString);
 226
 227     /**
 228         Returns @true if the directory contains any subdirectories (if a non
 229         empty @e filespec is given, only check for directories matching it).
 230         The hidden subdirectories are taken into account as well.
 231     */
 232     bool HasSubDirs(const wxString& dirspec = wxEmptyString);
 233
 234     /**
 235         Returns @true if the directory was successfully opened by a previous call to
 236         Open().
 237     */
 238     bool IsOpened();
 239
 240     /**
 241         Open the directory for enumerating, returns @true on success
 242         or @false if an error occurred.
 243     */
 244     bool Open(const wxString& dir);
 245
 246     /**
 247         Enumerate all files and directories under the given directory recursively
 248         calling the element of the provided wxDirTraverser
 249         object for each of them.
 250
 251         More precisely, the function will really recurse into subdirectories if
 252         @e flags contains @c wxDIR_DIRS flag. It will ignore the files (but
 253         still possibly recurse into subdirectories) if @c wxDIR_FILES flag is
 254         given.
 255
 256         For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called
 257         and @ref wxDirTraverser::onfile sink.OnFile is called for every file.
 258         Depending on the return value, the enumeration may continue or stop.
 259
 260         The function returns the total number of files found or @c (size_t)-1 on
 261         error.
 262
 263         See also: GetAllFiles()
 264     */
 265     size_t Traverse(wxDirTraverser& sink,
 266                     const wxString& filespec = wxEmptyString,
 267                     int flags = wxDIR_DEFAULT);
 268 };