include/wx/dir.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/dir.h
   3 // Purpose:     wxDir is a class for enumerating the files in a directory
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     08.12.99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1999 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_DIR_H_
  13 #define _WX_DIR_H_
  14
  15 #include "wx/longlong.h"
  16 #include "wx/string.h"
  17 #include "wx/filefn.h"      // for wxS_DIR_DEFAULT
  18
  19 class WXDLLIMPEXP_FWD_BASE wxArrayString;
  20
  21 // ----------------------------------------------------------------------------
  22 // constants
  23 // ----------------------------------------------------------------------------
  24
  25 // these flags define what kind of filenames is included in the list of files
  26 // enumerated by GetFirst/GetNext
  27 enum wxDirFlags
  28 {
  29     wxDIR_FILES     = 0x0001,       // include files
  30     wxDIR_DIRS      = 0x0002,       // include directories
  31     wxDIR_HIDDEN    = 0x0004,       // include hidden files
  32     wxDIR_DOTDOT    = 0x0008,       // include '.' and '..'
  33
  34     // by default, enumerate everything except '.' and '..'
  35     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
  36 };
  37
  38 // these constants are possible return value of wxDirTraverser::OnDir()
  39 enum wxDirTraverseResult
  40 {
  41     wxDIR_IGNORE = -1,      // ignore this directory but continue with others
  42     wxDIR_STOP,             // stop traversing
  43     wxDIR_CONTINUE          // continue into this directory
  44 };
  45
  46 // ----------------------------------------------------------------------------
  47 // wxDirTraverser: helper class for wxDir::Traverse()
  48 // ----------------------------------------------------------------------------
  49
  50 class WXDLLIMPEXP_BASE wxDirTraverser
  51 {
  52 public:
  53     /// a virtual dtor has been provided since this class has virtual members
  54     virtual ~wxDirTraverser() { }
  55     // called for each file found by wxDir::Traverse()
  56     //
  57     // return wxDIR_STOP or wxDIR_CONTINUE from here (wxDIR_IGNORE doesn't
  58     // make sense)
  59     virtual wxDirTraverseResult OnFile(const wxString& filename) = 0;
  60
  61     // called for each directory found by wxDir::Traverse()
  62     //
  63     // return one of the enum elements defined above
  64     virtual wxDirTraverseResult OnDir(const wxString& dirname) = 0;
  65
  66     // called for each directory which we couldn't open during our traversal
  67     // of the directory tree
  68     //
  69     // this method can also return either wxDIR_STOP, wxDIR_IGNORE or
  70     // wxDIR_CONTINUE but the latter is treated specially: it means to retry
  71     // opening the directory and so may lead to infinite loop if it is
  72     // returned unconditionally, be careful with this!
  73     //
  74     // the base class version always returns wxDIR_IGNORE
  75     virtual wxDirTraverseResult OnOpenError(const wxString& dirname);
  76 };
  77
  78 // ----------------------------------------------------------------------------
  79 // wxDir: portable equivalent of {open/read/close}dir functions
  80 // ----------------------------------------------------------------------------
  81
  82 class WXDLLIMPEXP_FWD_BASE wxDirData;
  83
  84 class WXDLLIMPEXP_BASE wxDir
  85 {
  86 public:
  87
  88     // ctors
  89     // -----
  90
  91     // default, use Open()
  92     wxDir() { m_data = NULL; }
  93
  94     // opens the directory for enumeration, use IsOpened() to test success
  95     wxDir(const wxString& dir);
  96
  97     // dtor calls Close() automatically
  98     ~wxDir() { Close(); }
  99
 100     // open the directory for enumerating
 101     bool Open(const wxString& dir);
 102
 103     // close the directory, Open() can be called again later
 104     void Close();
 105
 106     // returns true if the directory was successfully opened
 107     bool IsOpened() const;
 108
 109     // get the full name of the directory (without '/' at the end)
 110     wxString GetName() const;
 111
 112     // Same as GetName() but does include the trailing separator, unless the
 113     // string is empty (only for invalid directories).
 114     wxString GetNameWithSep() const;
 115
 116
 117     // file enumeration routines
 118     // -------------------------
 119
 120     // start enumerating all files matching filespec (or all files if it is
 121     // empty) and flags, return true on success
 122     bool GetFirst(wxString *filename,
 123                   const wxString& filespec = wxEmptyString,
 124                   int flags = wxDIR_DEFAULT) const;
 125
 126     // get next file in the enumeration started with GetFirst()
 127     bool GetNext(wxString *filename) const;
 128
 129     // return true if this directory has any files in it
 130     bool HasFiles(const wxString& spec = wxEmptyString) const;
 131
 132     // return true if this directory has any subdirectories
 133     bool HasSubDirs(const wxString& spec = wxEmptyString) const;
 134
 135     // enumerate all files in this directory and its subdirectories
 136     //
 137     // return the number of files found
 138     size_t Traverse(wxDirTraverser& sink,
 139                     const wxString& filespec = wxEmptyString,
 140                     int flags = wxDIR_DEFAULT) const;
 141
 142     // simplest version of Traverse(): get the names of all files under this
 143     // directory into filenames array, return the number of files
 144     static size_t GetAllFiles(const wxString& dirname,
 145                               wxArrayString *files,
 146                               const wxString& filespec = wxEmptyString,
 147                               int flags = wxDIR_DEFAULT);
 148
 149     // check if there any files matching the given filespec under the given
 150     // directory (i.e. searches recursively), return the file path if found or
 151     // empty string otherwise
 152     static wxString FindFirst(const wxString& dirname,
 153                               const wxString& filespec,
 154                               int flags = wxDIR_DEFAULT);
 155
 156 #if wxUSE_LONGLONG
 157     // returns the size of all directories recursively found in given path
 158     static wxULongLong GetTotalSize(const wxString &dir, wxArrayString *filesSkipped = NULL);
 159 #endif // wxUSE_LONGLONG
 160
 161
 162     // static utilities for directory management
 163     // (alias to wxFileName's functions for dirs)
 164     // -----------------------------------------
 165
 166     // test for existence of a directory with the given name
 167     static bool Exists(const wxString& dir);
 168
 169     static bool Make(const wxString &dir, int perm = wxS_DIR_DEFAULT,
 170                      int flags = 0);
 171
 172     static bool Remove(const wxString &dir, int flags = 0);
 173
 174
 175 private:
 176     friend class wxDirData;
 177
 178     wxDirData *m_data;
 179
 180     wxDECLARE_NO_COPY_CLASS(wxDir);
 181 };
 182
 183 #endif // _WX_DIR_H_
 184