interface/wx/dir.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dir.h
   3 // Purpose:     interface of wxDir and wxDirTraverser
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     Possible return values of wxDirTraverser callback functions.
  10 */
  11 enum wxDirTraverseResult
  12 {
  13     wxDIR_IGNORE = -1,  ///< Ignore this directory but continue with others.
  14     wxDIR_STOP,         ///< Stop traversing.
  15     wxDIR_CONTINUE      ///< Continue into this directory.
  16 };
  17
  18 /**
  19     @class wxDirTraverser
  20
  21     wxDirTraverser is an abstract interface which must be implemented by
  22     objects passed to wxDir::Traverse() function.
  23
  24     Example of use (this works almost like wxDir::GetAllFiles()):
  25
  26     @code
  27     class wxDirTraverserSimple : public wxDirTraverser
  28     {
  29     public:
  30         wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
  31
  32         virtual wxDirTraverseResult OnFile(const wxString& filename)
  33         {
  34             m_files.Add(filename);
  35             return wxDIR_CONTINUE;
  36         }
  37
  38         virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
  39         {
  40             return wxDIR_CONTINUE;
  41         }
  42
  43     private:
  44         wxArrayString& m_files;
  45     };
  46
  47     // get the names of all files in the array
  48     wxArrayString files;
  49     wxDirTraverserSimple traverser(files);
  50
  51     wxDir dir(dirname);
  52     dir.Traverse(traverser);
  53     @endcode
  54
  55     @library{wxbase}
  56     @category{file}
  57 */
  58 class wxDirTraverser
  59 {
  60 public:
  61     /**
  62         This function is called for each directory. It may return ::wxDIR_STOP
  63         to abort traversing completely, ::wxDIR_IGNORE to skip this directory
  64         but continue with others or ::wxDIR_CONTINUE to enumerate all files and
  65         subdirectories in this directory.
  66
  67         This is a pure virtual function and must be implemented in the derived
  68         class.
  69     */
  70     virtual wxDirTraverseResult OnDir(const wxString& dirname) = 0;
  71
  72     /**
  73         This function is called for each file. It may return ::wxDIR_STOP to
  74         abort traversing (for example, if the file being searched is found) or
  75         ::wxDIR_CONTINUE to proceed.
  76
  77         This is a pure virtual function and must be implemented in the derived
  78         class.
  79     */
  80     virtual wxDirTraverseResult OnFile(const wxString& filename) = 0;
  81
  82     /**
  83         This function is called for each directory which we failed to open for
  84         enumerating. It may return ::wxDIR_STOP to abort traversing completely,
  85         ::wxDIR_IGNORE to skip this directory but continue with others or
  86         ::wxDIR_CONTINUE to retry opening this directory once again.
  87
  88         The base class version always returns ::wxDIR_IGNORE.
  89     */
  90     virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
  91 };
  92
  93
  94
  95 /**
  96     These flags affect the behaviour of GetFirst/GetNext() and Traverse(),
  97     determining what types are included in the list of items they produce.
  98 */
  99 enum wxDirFlags
 100 {
 101     wxDIR_FILES     = 0x0001,   ///< Includes files.
 102     wxDIR_DIRS      = 0x0002,   ///< Includes directories.
 103     wxDIR_HIDDEN    = 0x0004,   ///< Includes hidden files.
 104     wxDIR_DOTDOT    = 0x0008,   ///< Includes "." and "..".
 105
 106     /**
 107         Don't follow symbolic links during the directory traversal.
 108
 109         This flag is ignored under systems not supporting symbolic links (i.e.
 110         non-Unix ones).
 111
 112         Notice that this flag is @e not included in wxDIR_DEFAULT and so the
 113         default behaviour of wxDir::Traverse() is to follow symbolic links,
 114         even if they lead outside of the directory being traversed.
 115
 116         @since 2.9.5
 117      */
 118     wxDIR_NO_FOLLOW = 0x0010,
 119
 120     /**
 121         Default directory traversal flags include both files and directories,
 122         even hidden.
 123
 124         Notice that by default wxDIR_NO_FOLLOW is @e not included, meaning that
 125         symbolic links are followed by default. If this is not desired, you
 126         must pass that flag explicitly.
 127      */
 128     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
 129 };
 130
 131 /**
 132     @class wxDir
 133
 134     wxDir is a portable equivalent of Unix open/read/closedir functions which
 135     allow enumerating of the files in a directory. wxDir allows to enumerate
 136     files as well as directories.
 137
 138     wxDir also provides a flexible way to enumerate files recursively using
 139     Traverse() or a simpler GetAllFiles() function.
 140
 141     Example of use:
 142
 143     @code
 144     wxDir dir(wxGetCwd());
 145
 146     if ( !dir.IsOpened() )
 147     {
 148         // deal with the error here - wxDir would already log an error message
 149         // explaining the exact reason of the failure
 150         return;
 151     }
 152
 153     puts("Enumerating object files in current directory:");
 154
 155     wxString filename;
 156
 157     bool cont = dir.GetFirst(&filename, filespec, flags);
 158     while ( cont )
 159     {
 160         printf("%s\n", filename.c_str());
 161
 162         cont = dir.GetNext(&filename);
 163     }
 164     @endcode
 165
 166     @library{wxbase}
 167     @category{file}
 168 */
 169 class wxDir
 170 {
 171 public:
 172     /**
 173         Default constructor, use Open() afterwards.
 174     */
 175     wxDir();
 176     /**
 177         Opens the directory for enumeration, use IsOpened() to test for errors.
 178     */
 179     wxDir(const wxString& dir);
 180
 181     /**
 182         Destructor cleans up the associated resources by calling Close().
 183
 184         It is not virtual and so this class is not meant to be used
 185         polymorphically.
 186     */
 187     ~wxDir();
 188
 189     /**
 190         Close the directory.
 191
 192         The object can't be used after closing it, but Open() may be called
 193         again to reopen it later.
 194
 195         @since 2.9.5
 196     */
 197     void Close();
 198
 199     /**
 200         Test for existence of a directory with the given name.
 201     */
 202     static bool Exists(const wxString& dir);
 203
 204     /**
 205         The function returns the path of the first file matching the given
 206         @a filespec or an empty string if there are no files matching it.
 207
 208         The @a flags parameter may or may not include ::wxDIR_FILES, the
 209         function always behaves as if it were specified. By default, @a flags
 210         includes ::wxDIR_DIRS and so the function recurses into the
 211         subdirectories but if this flag is not specified, the function
 212         restricts the search only to the directory @a dirname itself.
 213         See ::wxDirFlags for the list of the possible flags.
 214
 215         @see Traverse()
 216     */
 217     static wxString FindFirst(const wxString& dirname,
 218                               const wxString& filespec,
 219                               int flags = wxDIR_DEFAULT);
 220
 221     /**
 222         The function appends the names of all the files under directory
 223         @a dirname to the array @a files (note that its old content is
 224         preserved). Only files matching the @a filespec are taken, with empty
 225         spec matching all the files.
 226
 227         The @a flags parameter should always include ::wxDIR_FILES or the array
 228         would be unchanged and should include ::wxDIR_DIRS flag to recurse into
 229         subdirectories (both flags are included in the value by default).
 230         See ::wxDirFlags for the list of the possible flags.
 231
 232         @return Returns the total number of files found while traversing
 233                 the directory @a dirname (i.e. the number of entries appended
 234                 to the @a files array).
 235
 236         @see Traverse()
 237     */
 238     static size_t GetAllFiles(const wxString& dirname, wxArrayString* files,
 239                               const wxString& filespec = wxEmptyString,
 240                               int flags = wxDIR_DEFAULT);
 241
 242     /**
 243         Start enumerating all files matching @a filespec (or all files if it is
 244         empty) and @e flags, return @true on success.
 245         See ::wxDirFlags for the list of the possible flags.
 246     */
 247     bool GetFirst(wxString* filename,
 248                   const wxString& filespec = wxEmptyString,
 249                   int flags = wxDIR_DEFAULT) const;
 250
 251     /**
 252         Returns the name of the directory itself.
 253
 254         The returned string does not have the trailing path separator (slash or
 255         backslash).
 256
 257         Notice that in spite of this the last character of the returned string
 258         can still be the path separator if this directory is the root one.
 259         Because of this, don't append @c wxFILE_SEP_PATH to the returned value
 260         if you do need a slash-terminated directory name but use
 261         GetNameWithSep() instead to avoid having duplicate consecutive slashes.
 262     */
 263     wxString GetName() const;
 264
 265     /**
 266         Returns the name of the directory with the path separator appended.
 267
 268         The last character of the returned string is always @c wxFILE_SEP_PATH
 269         unless the string is empty, indicating that this directory is invalid.
 270
 271         @see GetName()
 272
 273         @since 2.9.4
 274      */
 275     wxString GetNameWithSep() const;
 276
 277     /**
 278         Continue enumerating files which satisfy the criteria specified by the
 279         last call to GetFirst().
 280     */
 281     bool GetNext(wxString* filename) const;
 282
 283     /**
 284         Returns the size (in bytes) of all files recursively found in @c dir or
 285         @c wxInvalidSize in case of error.
 286
 287         In case it happens that while traversing folders a file's size cannot
 288         be read, that file is added to the @a filesSkipped array, if not @NULL,
 289         and then skipped. This usually happens with some special folders which
 290         are locked by the operating system or by another process. Remember that
 291         when the size of @a filesSkipped is not zero, then the returned value
 292         is not 100% accurate and, if the skipped files were big, it could be
 293         far from real size of the directory.
 294
 295         @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
 296     */
 297     static wxULongLong GetTotalSize(const wxString& dir,
 298                                     wxArrayString* filesSkipped = NULL);
 299
 300     /**
 301         Returns @true if the directory contains any files matching the given
 302         @a filespec. If @a filespec is empty, look for any files at all. In any
 303         case, even hidden files are taken into account.
 304     */
 305     bool HasFiles(const wxString& filespec = wxEmptyString) const;
 306
 307     /**
 308         Returns @true if the directory contains any subdirectories (if a non
 309         empty @a filespec is given, only check for directories matching it).
 310         The hidden subdirectories are taken into account as well.
 311     */
 312     bool HasSubDirs(const wxString& dirspec = wxEmptyString) const;
 313
 314     /**
 315         Returns @true if the directory was successfully opened by a previous
 316         call to Open().
 317     */
 318     bool IsOpened() const;
 319
 320     /**
 321         Creates a directory.
 322
 323         This is just an alias for wxFileName::Mkdir(); refer to that function
 324         for more info.
 325     */
 326     static bool Make(const wxString &dir, int perm = wxS_DIR_DEFAULT,
 327                      int flags = 0);
 328
 329     /**
 330         Open the directory for enumerating, returns @true on success or @false
 331         if an error occurred.
 332     */
 333     bool Open(const wxString& dir);
 334
 335     /**
 336         Removes a directory.
 337
 338         This is just an alias for wxFileName::Rmdir(); refer to that function
 339         for more info.
 340     */
 341     static bool Remove(const wxString &dir, int flags = 0);
 342
 343     /**
 344         Enumerate all files and directories under the given directory.
 345
 346         If @a flags contains ::wxDIR_DIRS this enumeration is recursive, i.e.
 347         all the subdirectories of the given one and the files inside them will
 348         be traversed. Otherwise only the files in this directory itself are.
 349
 350         If @a flags doesn't contain ::wxDIR_FILES then only subdirectories are
 351         examined but not normal files. It doesn't make sense to not specify
 352         either ::wxDIR_DIRS or ::wxDIR_FILES and usually both of them should be
 353         specified, as is the case by default.
 354
 355         For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()"
 356         is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
 357         for every file. Depending on the return value, the enumeration may
 358         continue or stop. If entering a subdirectory fails, @ref
 359         wxDirTraverser::OnOpenError() "sink.OnOpenError()" is called.
 360
 361         The function returns the total number of files found or @c "(size_t)-1"
 362         on error.
 363
 364         See ::wxDirFlags for the full list of the possible flags.
 365
 366         @see GetAllFiles()
 367     */
 368     size_t Traverse(wxDirTraverser& sink,
 369                     const wxString& filespec = wxEmptyString,
 370                     int flags = wxDIR_DEFAULT) const;
 371 };
 372