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
  18 class WXDLLIMPEXP_FWD_BASE wxArrayString;
  19
  20 // ----------------------------------------------------------------------------
  21 // constants
  22 // ----------------------------------------------------------------------------
  23
  24 // these flags define what kind of filenames is included in the list of files
  25 // enumerated by GetFirst/GetNext
  26 enum wxDirFlags
  27 {
  28     wxDIR_FILES     = 0x0001,       // include files
  29     wxDIR_DIRS      = 0x0002,       // include directories
  30     wxDIR_HIDDEN    = 0x0004,       // include hidden files
  31     wxDIR_DOTDOT    = 0x0008,       // include '.' and '..'
  32
  33     // by default, enumerate everything except '.' and '..'
  34     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
  35 };
  36
  37 // these constants are possible return value of wxDirTraverser::OnDir()
  38 enum wxDirTraverseResult
  39 {
  40     wxDIR_IGNORE = -1,      // ignore this directory but continue with others
  41     wxDIR_STOP,             // stop traversing
  42     wxDIR_CONTINUE          // continue into this directory
  43 };
  44
  45 // ----------------------------------------------------------------------------
  46 // wxDirTraverser: helper class for wxDir::Traverse()
  47 // ----------------------------------------------------------------------------
  48
  49 class WXDLLIMPEXP_BASE wxDirTraverser
  50 {
  51 public:
  52     /// a virtual dtor has been provided since this class has virtual members
  53     virtual ~wxDirTraverser() { }
  54     // called for each file found by wxDir::Traverse()
  55     //
  56     // return wxDIR_STOP or wxDIR_CONTINUE from here (wxDIR_IGNORE doesn't
  57     // make sense)
  58     virtual wxDirTraverseResult OnFile(const wxString& filename) = 0;
  59
  60     // called for each directory found by wxDir::Traverse()
  61     //
  62     // return one of the enum elements defined above
  63     virtual wxDirTraverseResult OnDir(const wxString& dirname) = 0;
  64
  65     // called for each directory which we couldn't open during our traversal
  66     // of the directory tree
  67     //
  68     // this method can also return either wxDIR_STOP, wxDIR_IGNORE or
  69     // wxDIR_CONTINUE but the latter is treated specially: it means to retry
  70     // opening the directory and so may lead to infinite loop if it is
  71     // returned unconditionally, be careful with this!
  72     //
  73     // the base class version always returns wxDIR_IGNORE
  74     virtual wxDirTraverseResult OnOpenError(const wxString& dirname);
  75 };
  76
  77 // ----------------------------------------------------------------------------
  78 // wxDir: portable equivalent of {open/read/close}dir functions
  79 // ----------------------------------------------------------------------------
  80
  81 class WXDLLIMPEXP_FWD_BASE wxDirData;
  82
  83 class WXDLLIMPEXP_BASE wxDir
  84 {
  85 public:
  86     // test for existence of a directory with the given name
  87     static bool Exists(const wxString& dir);
  88
  89     // ctors
  90     // -----
  91
  92     // default, use Open()
  93     wxDir() { m_data = NULL; }
  94
  95     // opens the directory for enumeration, use IsOpened() to test success
  96     wxDir(const wxString& dir);
  97
  98     // dtor cleans up the associated resources
  99     ~wxDir();
 100
 101     // open the directory for enumerating
 102     bool Open(const wxString& dir);
 103
 104     // returns true if the directory was successfully opened
 105     bool IsOpened() const;
 106
 107     // get the full name of the directory (without '/' at the end)
 108     wxString GetName() const;
 109
 110     // file enumeration routines
 111     // -------------------------
 112
 113     // start enumerating all files matching filespec (or all files if it is
 114     // empty) and flags, return true on success
 115     bool GetFirst(wxString *filename,
 116                   const wxString& filespec = wxEmptyString,
 117                   int flags = wxDIR_DEFAULT) const;
 118
 119     // get next file in the enumeration started with GetFirst()
 120     bool GetNext(wxString *filename) const;
 121
 122     // return true if this directory has any files in it
 123     bool HasFiles(const wxString& spec = wxEmptyString) const;
 124
 125     // return true if this directory has any subdirectories
 126     bool HasSubDirs(const wxString& spec = wxEmptyString) const;
 127
 128     // enumerate all files in this directory and its subdirectories
 129     //
 130     // return the number of files found
 131     size_t Traverse(wxDirTraverser& sink,
 132                     const wxString& filespec = wxEmptyString,
 133                     int flags = wxDIR_DEFAULT) const;
 134
 135     // simplest version of Traverse(): get the names of all files under this
 136     // directory into filenames array, return the number of files
 137     static size_t GetAllFiles(const wxString& dirname,
 138                               wxArrayString *files,
 139                               const wxString& filespec = wxEmptyString,
 140                               int flags = wxDIR_DEFAULT);
 141
 142     // check if there any files matching the given filespec under the given
 143     // directory (i.e. searches recursively), return the file path if found or
 144     // empty string otherwise
 145     static wxString FindFirst(const wxString& dirname,
 146                               const wxString& filespec,
 147                               int flags = wxDIR_DEFAULT);
 148
 149 #if wxUSE_LONGLONG
 150     // returns the size of all directories recursively found in given path
 151     static wxULongLong GetTotalSize(const wxString &dir, wxArrayString *filesSkipped = NULL);
 152 #endif // wxUSE_LONGLONG
 153
 154 private:
 155     friend class wxDirData;
 156
 157     wxDirData *m_data;
 158
 159     wxDECLARE_NO_COPY_CLASS(wxDir);
 160 };
 161
 162 #endif // _WX_DIR_H_
 163