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 affect the behaviour of GetFirst/GetNext() and Traverse(),
  98     determining what types are included in the list of items they produce.
  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     /**
 108         Don't follow symbolic links during the directory traversal.
 109
 110         This flag is ignored under systems not supporting symbolic links (i.e.
 111         non-Unix ones).
 112
 113         Notice that this flag is @e not included in wxDIR_DEFAULT and so the
 114         default behaviour of wxDir::Traverse() is to follow symbolic links,
 115         even if they lead outside of the directory being traversed.
 116
 117         @since 2.9.5
 118      */
 119     wxDIR_NO_FOLLOW = 0x0010,
 120
 121     /**
 122         Default directory traversal flags include both files and directories,
 123         even hidden.
 124
 125         Notice that by default wxDIR_NO_FOLLOW is @e not included, meaning that
 126         symbolic links are followed by default. If this is not desired, you
 127         must pass that flag explicitly.
 128      */
 129     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
 130 };
 131
 132 /**
 133     @class wxDir
 134
 135     wxDir is a portable equivalent of Unix open/read/closedir functions which
 136     allow enumerating of the files in a directory. wxDir allows to enumerate
 137     files as well as directories.
 138
 139     wxDir also provides a flexible way to enumerate files recursively using
 140     Traverse() or a simpler GetAllFiles() function.
 141
 142     Example of use:
 143
 144     @code
 145     wxDir dir(wxGetCwd());
 146
 147     if ( !dir.IsOpened() )
 148     {
 149         // deal with the error here - wxDir would already log an error message
 150         // explaining the exact reason of the failure
 151         return;
 152     }
 153
 154     puts("Enumerating object files in current directory:");
 155
 156     wxString filename;
 157
 158     bool cont = dir.GetFirst(&filename, filespec, flags);
 159     while ( cont )
 160     {
 161         printf("%s\n", filename.c_str());
 162
 163         cont = dir.GetNext(&filename);
 164     }
 165     @endcode
 166
 167     @library{wxbase}
 168     @category{file}
 169 */
 170 class wxDir
 171 {
 172 public:
 173     /**
 174         Default constructor, use Open() afterwards.
 175     */
 176     wxDir();
 177     /**
 178         Opens the directory for enumeration, use IsOpened() to test for errors.
 179     */
 180     wxDir(const wxString& dir);
 181
 182     /**
 183         Destructor cleans up the associated resources by calling Close().
 184
 185         It is not virtual and so this class is not meant to be used
 186         polymorphically.
 187     */
 188     ~wxDir();
 189
 190     /**
 191         Close the directory.
 192
 193         The object can't be used after closing it, but Open() may be called
 194         again to reopen it later.
 195
 196         @since 2.9.5
 197     */
 198     void Close();
 199
 200     /**
 201         Test for existence of a directory with the given name.
 202     */
 203     static bool Exists(const wxString& dir);
 204
 205     /**
 206         The function returns the path of the first file matching the given
 207         @a filespec or an empty string if there are no files matching it.
 208
 209         The @a flags parameter may or may not include ::wxDIR_FILES, the
 210         function always behaves as if it were specified. By default, @a flags
 211         includes ::wxDIR_DIRS and so the function recurses into the
 212         subdirectories but if this flag is not specified, the function
 213         restricts the search only to the directory @a dirname itself.
 214         See ::wxDirFlags for the list of the possible flags.
 215
 216         @see Traverse()
 217     */
 218     static wxString FindFirst(const wxString& dirname,
 219                               const wxString& filespec,
 220                               int flags = wxDIR_DEFAULT);
 221
 222     /**
 223         The function appends the names of all the files under directory
 224         @a dirname to the array @a files (note that its old content is
 225         preserved). Only files matching the @a filespec are taken, with empty
 226         spec matching all the files.
 227
 228         The @a flags parameter should always include ::wxDIR_FILES or the array
 229         would be unchanged and should include ::wxDIR_DIRS flag to recurse into
 230         subdirectories (both flags are included in the value by default).
 231         See ::wxDirFlags for the list of the possible flags.
 232
 233         @return Returns the total number of files found while traversing
 234                 the directory @a dirname (i.e. the number of entries appended
 235                 to the @a files array).
 236
 237         @see Traverse()
 238     */
 239     static size_t GetAllFiles(const wxString& dirname, wxArrayString* files,
 240                               const wxString& filespec = wxEmptyString,
 241                               int flags = wxDIR_DEFAULT);
 242
 243     /**
 244         Start enumerating all files matching @a filespec (or all files if it is
 245         empty) and @e flags, return @true on success.
 246         See ::wxDirFlags for the list of the possible flags.
 247     */
 248     bool GetFirst(wxString* filename,
 249                   const wxString& filespec = wxEmptyString,
 250                   int flags = wxDIR_DEFAULT) const;
 251
 252     /**
 253         Returns the name of the directory itself.
 254
 255         The returned string does not have the trailing path separator (slash or
 256         backslash).
 257
 258         Notice that in spite of this the last character of the returned string
 259         can still be the path separator if this directory is the root one.
 260         Because of this, don't append ::wxFILE_SEP_PATH to the returned value
 261         if you do need a slash-terminated directory name but use
 262         GetNameWithSep() instead to avoid having duplicate consecutive slashes.
 263     */
 264     wxString GetName() const;
 265
 266     /**
 267         Returns the name of the directory with the path separator appended.
 268
 269         The last character of the returned string is always ::wxFILE_SEP_PATH
 270         unless the string is empty, indicating that this directory is invalid.
 271
 272         @see GetName()
 273
 274         @since 2.9.4
 275      */
 276     wxString GetNameWithSep() const;
 277
 278     /**
 279         Continue enumerating files which satisfy the criteria specified by the
 280         last call to GetFirst().
 281     */
 282     bool GetNext(wxString* filename) const;
 283
 284     /**
 285         Returns the size (in bytes) of all files recursively found in @c dir or
 286         @c wxInvalidSize in case of error.
 287
 288         In case it happens that while traversing folders a file's size cannot
 289         be read, that file is added to the @a filesSkipped array, if not @NULL,
 290         and then skipped. This usually happens with some special folders which
 291         are locked by the operating system or by another process. Remember that
 292         when the size of @a filesSkipped is not zero, then the returned value
 293         is not 100% accurate and, if the skipped files were big, it could be
 294         far from real size of the directory.
 295
 296         @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
 297     */
 298     static wxULongLong GetTotalSize(const wxString& dir,
 299                                     wxArrayString* filesSkipped = NULL);
 300
 301     /**
 302         Returns @true if the directory contains any files matching the given
 303         @a filespec. If @a filespec is empty, look for any files at all. In any
 304         case, even hidden files are taken into account.
 305     */
 306     bool HasFiles(const wxString& filespec = wxEmptyString) const;
 307
 308     /**
 309         Returns @true if the directory contains any subdirectories (if a non
 310         empty @a filespec is given, only check for directories matching it).
 311         The hidden subdirectories are taken into account as well.
 312     */
 313     bool HasSubDirs(const wxString& dirspec = wxEmptyString) const;
 314
 315     /**
 316         Returns @true if the directory was successfully opened by a previous
 317         call to Open().
 318     */
 319     bool IsOpened() const;
 320
 321     /**
 322         Creates a directory.
 323
 324         This is just an alias for wxFileName::Mkdir(); refer to that function
 325         for more info.
 326     */
 327     static bool Make(const wxString &dir, int perm = wxS_DIR_DEFAULT,
 328                      int flags = 0);
 329
 330     /**
 331         Open the directory for enumerating, returns @true on success or @false
 332         if an error occurred.
 333     */
 334     bool Open(const wxString& dir);
 335
 336     /**
 337         Removes a directory.
 338
 339         This is just an alias for wxFileName::Rmdir(); refer to that function
 340         for more info.
 341     */
 342     static bool Remove(const wxString &dir, int flags = 0);
 343
 344     /**
 345         Enumerate all files and directories under the given directory.
 346
 347         If @a flags contains ::wxDIR_DIRS this enumeration is recursive, i.e.
 348         all the subdirectories of the given one and the files inside them will
 349         be traversed. Otherwise only the files in this directory itself are.
 350
 351         If @a flags doesn't contain ::wxDIR_FILES then only subdirectories are
 352         examined but not normal files. It doesn't make sense to not specify
 353         either ::wxDIR_DIRS or ::wxDIR_FILES and usually both of them should be
 354         specified, as is the case by default.
 355
 356         For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()"
 357         is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
 358         for every file. Depending on the return value, the enumeration may
 359         continue or stop. If entering a subdirectory fails, @ref
 360         wxDirTraverser::OnOpenError() "sink.OnOpenError()" is called.
 361
 362         The function returns the total number of files found or @c "(size_t)-1"
 363         on error.
 364
 365         See ::wxDirFlags for the full list of the possible flags.
 366
 367         @see GetAllFiles()
 368     */
 369     size_t Traverse(wxDirTraverser& sink,
 370                     const wxString& filespec = wxEmptyString,
 371                     int flags = wxDIR_DEFAULT) const;
 372 };
 373