]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: dir.h | |
3 | // Purpose: interface of wxDirTraverser | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxDirTraverser | |
11 | @wxheader{dir.h} | |
12 | ||
13 | wxDirTraverser is an abstract interface which must be implemented by objects | |
14 | passed to wxDir::Traverse function. | |
15 | ||
16 | Example of use (this works almost like wxDir::GetAllFiles): | |
17 | ||
18 | @code | |
19 | class wxDirTraverserSimple : public wxDirTraverser | |
20 | { | |
21 | public: | |
22 | wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } | |
23 | ||
24 | virtual wxDirTraverseResult OnFile(const wxString& filename) | |
25 | { | |
26 | m_files.Add(filename); | |
27 | return wxDIR_CONTINUE; | |
28 | } | |
29 | ||
30 | virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) | |
31 | { | |
32 | return wxDIR_CONTINUE; | |
33 | } | |
34 | ||
35 | private: | |
36 | wxArrayString& m_files; | |
37 | }; | |
38 | ||
39 | // get the names of all files in the array | |
40 | wxArrayString files; | |
41 | wxDirTraverserSimple traverser(files); | |
42 | ||
43 | wxDir dir(dirname); | |
44 | dir.Traverse(traverser); | |
45 | @endcode | |
46 | ||
47 | @library{wxbase} | |
48 | @category{file} | |
49 | */ | |
50 | class wxDirTraverser | |
51 | { | |
52 | public: | |
53 | /** | |
54 | This function is called for each directory. It may return @c wxDIR_STOP | |
55 | to abort traversing completely, @c wxDIR_IGNORE to skip this directory but | |
56 | continue with others or @c wxDIR_CONTINUE to enumerate all files and | |
57 | subdirectories in this directory. | |
58 | This is a pure virtual function and must be implemented in the derived class. | |
59 | */ | |
60 | virtual wxDirTraverseResult OnDir(const wxString& dirname); | |
61 | ||
62 | /** | |
63 | This function is called for each file. It may return @c wxDIR_STOP to abort | |
64 | traversing (for example, if the file being searched is found) or | |
65 | @c wxDIR_CONTINUE to proceed. | |
66 | This is a pure virtual function and must be implemented in the derived class. | |
67 | */ | |
68 | virtual wxDirTraverseResult OnFile(const wxString& filename); | |
69 | ||
70 | /** | |
71 | This function is called for each directory which we failed to open for | |
72 | enumerating. It may return @c wxDIR_STOP to abort traversing completely, | |
73 | @c wxDIR_IGNORE to skip this directory but continue with others or | |
74 | @c wxDIR_CONTINUE to retry opening this directory once again. | |
75 | The base class version always returns @c wxDIR_IGNORE. | |
76 | */ | |
77 | virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); | |
78 | }; | |
79 | ||
80 | ||
81 | ||
82 | /** | |
83 | @class wxDir | |
84 | @wxheader{dir.h} | |
85 | ||
86 | wxDir is a portable equivalent of Unix open/read/closedir functions which | |
87 | allow enumerating of the files in a directory. wxDir allows to enumerate files | |
88 | as well as directories. | |
89 | ||
90 | wxDir also provides a flexible way to enumerate files recursively using | |
91 | wxDir::Traverse or a simpler | |
92 | wxDir::GetAllFiles function. | |
93 | ||
94 | Example of use: | |
95 | ||
96 | @code | |
97 | wxDir dir(wxGetCwd()); | |
98 | ||
99 | if ( !dir.IsOpened() ) | |
100 | { | |
101 | // deal with the error here - wxDir would already log an error message | |
102 | // explaining the exact reason of the failure | |
103 | return; | |
104 | } | |
105 | ||
106 | puts("Enumerating object files in current directory:"); | |
107 | ||
108 | wxString filename; | |
109 | ||
110 | bool cont = dir.GetFirst(, filespec, flags); | |
111 | while ( cont ) | |
112 | { | |
113 | printf("%s\n", filename.c_str()); | |
114 | ||
115 | cont = dir.GetNext(); | |
116 | } | |
117 | @endcode | |
118 | ||
119 | @library{wxbase} | |
120 | @category{file} | |
121 | */ | |
122 | class wxDir | |
123 | { | |
124 | public: | |
125 | //@{ | |
126 | /** | |
127 | Opens the directory for enumeration, use IsOpened() | |
128 | to test for errors. | |
129 | */ | |
130 | wxDir(); | |
131 | wxDir(const wxString& dir); | |
132 | //@} | |
133 | ||
134 | /** | |
135 | Destructor cleans up the associated resources. It is not virtual and so this | |
136 | class is not meant to be used polymorphically. | |
137 | */ | |
138 | ~wxDir(); | |
139 | ||
140 | /** | |
141 | Test for existence of a directory with the given name | |
142 | */ | |
143 | static bool Exists(const wxString& dir); | |
144 | ||
145 | /** | |
146 | The function returns the path of the first file matching the given @e filespec | |
147 | or an empty string if there are no files matching it. | |
148 | The @a flags parameter may or may not include @c wxDIR_FILES, the | |
149 | function always behaves as if it were specified. By default, @a flags | |
150 | includes @c wxDIR_DIRS and so the function recurses into the subdirectories | |
151 | but if this flag is not specified, the function restricts the search only to | |
152 | the directory @a dirname itself. | |
153 | See also: Traverse() | |
154 | */ | |
155 | static wxString FindFirst(const wxString& dirname, | |
156 | const wxString& filespec, | |
157 | int flags = wxDIR_DEFAULT); | |
158 | ||
159 | /** | |
160 | The function appends the names of all the files under directory @a dirname | |
161 | to the array @a files (note that its old content is preserved). Only files | |
162 | matching the @a filespec are taken, with empty spec matching all the files. | |
163 | The @a flags parameter should always include @c wxDIR_FILES or the array | |
164 | would be unchanged and should include @c wxDIR_DIRS flag to recurse into | |
165 | subdirectories (both flags are included in the value by default). | |
166 | See also: Traverse() | |
167 | */ | |
168 | static size_t GetAllFiles(const wxString& dirname, | |
169 | wxArrayString* files, | |
170 | const wxString& filespec = wxEmptyString, | |
171 | int flags = wxDIR_DEFAULT); | |
172 | ||
173 | /** | |
174 | Start enumerating all files matching @a filespec (or all files if it is | |
175 | empty) and @e flags, return @true on success. | |
176 | */ | |
177 | bool GetFirst(wxString* filename, | |
178 | const wxString& filespec = wxEmptyString, | |
179 | int flags = wxDIR_DEFAULT) const; | |
180 | ||
181 | /** | |
182 | Returns the name of the directory itself. The returned string does not have the | |
183 | trailing path separator (slash or backslash). | |
184 | */ | |
185 | wxString GetName() const; | |
186 | ||
187 | /** | |
188 | Continue enumerating files which satisfy the criteria specified by the last | |
189 | call to GetFirst(). | |
190 | */ | |
191 | bool GetNext(wxString* filename) const; | |
192 | ||
193 | /** | |
194 | Returns the size (in bytes) of all files recursively found in @c dir or | |
195 | @c wxInvalidSize in case of error. | |
196 | In case it happens that while traversing folders a file's size can not be read, | |
197 | that file is added to the @c filesSkipped array, if not @NULL, and then | |
198 | skipped. | |
199 | This usually happens with some special folders which are locked by the | |
200 | operating system | |
201 | or by another process. Remember that when @c filesSkipped-GetCount() is not | |
202 | zero, | |
203 | then the returned value is not 100% accurate and, if the skipped files were | |
204 | big, it could be | |
205 | far from real size of the directory. | |
206 | See also: wxFileName::GetHumanReadableSize, | |
207 | wxGetDiskSpace() | |
208 | */ | |
209 | static wxULongLong GetTotalSize(const wxString& dir, | |
210 | wxArrayString* filesSkipped = NULL); | |
211 | ||
212 | /** | |
213 | Returns @true if the directory contains any files matching the given | |
214 | @e filespec. If @a filespec is empty, look for any files at all. In any | |
215 | case, even hidden files are taken into account. | |
216 | */ | |
217 | bool HasFiles(const wxString& filespec = wxEmptyString); | |
218 | ||
219 | /** | |
220 | Returns @true if the directory contains any subdirectories (if a non | |
221 | empty @e filespec is given, only check for directories matching it). | |
222 | The hidden subdirectories are taken into account as well. | |
223 | */ | |
224 | bool HasSubDirs(const wxString& dirspec = wxEmptyString); | |
225 | ||
226 | /** | |
227 | Returns @true if the directory was successfully opened by a previous call to | |
228 | Open(). | |
229 | */ | |
230 | bool IsOpened() const; | |
231 | ||
232 | /** | |
233 | Open the directory for enumerating, returns @true on success | |
234 | or @false if an error occurred. | |
235 | */ | |
236 | bool Open(const wxString& dir); | |
237 | ||
238 | /** | |
239 | Enumerate all files and directories under the given directory recursively | |
240 | calling the element of the provided wxDirTraverser | |
241 | object for each of them. | |
242 | More precisely, the function will really recurse into subdirectories if | |
243 | @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but | |
244 | still possibly recurse into subdirectories) if @c wxDIR_FILES flag is | |
245 | given. | |
246 | For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called | |
247 | and @ref wxDirTraverser::onfile sink.OnFile is called for every file. | |
248 | Depending on the return value, the enumeration may continue or stop. | |
249 | The function returns the total number of files found or @c (size_t)-1 on | |
250 | error. | |
251 | See also: GetAllFiles() | |
252 | */ | |
253 | size_t Traverse(wxDirTraverser& sink, | |
254 | const wxString& filespec = wxEmptyString, | |
255 | int flags = wxDIR_DEFAULT); | |
256 | }; | |
257 |