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: dir.h 53135 2008-04-12 02:31:04Z VZ $
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
18class 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
26enum
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()
38enum 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
49class WXDLLIMPEXP_BASE wxDirTraverser
50{
51public:
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 tyree
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
81class WXDLLIMPEXP_FWD_BASE wxDirData;
82
83class WXDLLIMPEXP_BASE wxDir
84{
85public:
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 ressources
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);
124
125    // return true if this directory has any subdirectories
126    bool HasSubDirs(const wxString& spec = wxEmptyString);
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    // returns the size of all directories recursively found in given path
150    static wxULongLong GetTotalSize(const wxString &dir, wxArrayString *filesSkipped = NULL);
151
152private:
153    friend class wxDirData;
154
155    wxDirData *m_data;
156
157    DECLARE_NO_COPY_CLASS(wxDir)
158};
159
160#endif // _WX_DIR_H_
161
162