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 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16     #pragma interface "dir.h"
  17 #endif
  18
  19 #ifndef WX_PRECOMP
  20     #include "wx/string.h"
  21 #endif
  22
  23 class WXDLLIMPEXP_BASE wxArrayString;
  24
  25 // ----------------------------------------------------------------------------
  26 // constants
  27 // ----------------------------------------------------------------------------
  28
  29 // these flags define what kind of filenames is included in the list of files
  30 // enumerated by GetFirst/GetNext
  31 enum
  32 {
  33     wxDIR_FILES     = 0x0001,       // include files
  34     wxDIR_DIRS      = 0x0002,       // include directories
  35     wxDIR_HIDDEN    = 0x0004,       // include hidden files
  36     wxDIR_DOTDOT    = 0x0008,       // include '.' and '..'
  37
  38     // by default, enumerate everything except '.' and '..'
  39     wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
  40 };
  41
  42 // these constants are possible return value of wxDirTraverser::OnDir()
  43 enum wxDirTraverseResult
  44 {
  45     wxDIR_IGNORE = -1,      // ignore this directory but continue with others
  46     wxDIR_STOP,             // stop traversing
  47     wxDIR_CONTINUE          // continue into this directory
  48 };
  49
  50 // ----------------------------------------------------------------------------
  51 // wxDirTraverser: helper class for wxDir::Traverse()
  52 // ----------------------------------------------------------------------------
  53
  54 class WXDLLIMPEXP_BASE wxDirTraverser
  55 {
  56 public:
  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 tyree
  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_BASE wxDirData;
  85
  86 class WXDLLIMPEXP_BASE wxDir
  87 {
  88 public:
  89     // test for existence of a directory with the given name
  90     static bool Exists(const wxString& dir);
  91
  92     // ctors
  93     // -----
  94
  95     // default, use Open()
  96     wxDir() { m_data = NULL; }
  97
  98     // opens the directory for enumeration, use IsOpened() to test success
  99     wxDir(const wxString& dir);
 100
 101     // dtor cleans up the associated ressources
 102     ~wxDir();
 103
 104     // open the directory for enumerating
 105     bool Open(const wxString& dir);
 106
 107     // returns TRUE if the directory was successfully opened
 108     bool IsOpened() const;
 109
 110     // get the full name of the directory (without '/' at the end)
 111     wxString GetName() const;
 112
 113     // file enumeration routines
 114     // -------------------------
 115
 116     // start enumerating all files matching filespec (or all files if it is
 117     // empty) and flags, return TRUE on success
 118     bool GetFirst(wxString *filename,
 119                   const wxString& filespec = wxEmptyString,
 120                   int flags = wxDIR_DEFAULT) const;
 121
 122     // get next file in the enumeration started with GetFirst()
 123     bool GetNext(wxString *filename) const;
 124
 125     // return true if this directory has any files in it
 126     bool HasFiles(const wxString& spec = wxEmptyString);
 127
 128     // return true if this directory has any subdirectories
 129     bool HasSubDirs(const wxString& spec = wxEmptyString);
 130
 131     // enumerate all files in this directory and its subdirectories
 132     //
 133     // return the number of files found
 134     size_t Traverse(wxDirTraverser& sink,
 135                     const wxString& filespec = wxEmptyString,
 136                     int flags = wxDIR_DEFAULT) const;
 137
 138     // simplest version of Traverse(): get the names of all files under this
 139     // directory into filenames array, return the number of files
 140     static size_t GetAllFiles(const wxString& dirname,
 141                               wxArrayString *files,
 142                               const wxString& filespec = wxEmptyString,
 143                               int flags = wxDIR_DEFAULT);
 144
 145 private:
 146     friend class wxDirData;
 147
 148     wxDirData *m_data;
 149
 150     DECLARE_NO_COPY_CLASS(wxDir)
 151 };
 152
 153 #endif // _WX_DIR_H_
 154