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