]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: dir.h | |
3 | // Purpose: interface of wxDir and wxDirTraverser | |
4 | // Author: wxWidgets team | |
5 | // Licence: wxWindows licence | |
6 | ///////////////////////////////////////////////////////////////////////////// | |
7 | ||
8 | /** | |
9 | Possible return values of wxDirTraverser callback functions. | |
10 | */ | |
11 | enum wxDirTraverseResult | |
12 | { | |
13 | wxDIR_IGNORE = -1, ///< Ignore this directory but continue with others. | |
14 | wxDIR_STOP, ///< Stop traversing. | |
15 | wxDIR_CONTINUE ///< Continue into this directory. | |
16 | }; | |
17 | ||
18 | /** | |
19 | @class wxDirTraverser | |
20 | ||
21 | wxDirTraverser is an abstract interface which must be implemented by | |
22 | objects passed to wxDir::Traverse() function. | |
23 | ||
24 | Example of use (this works almost like wxDir::GetAllFiles()): | |
25 | ||
26 | @code | |
27 | class wxDirTraverserSimple : public wxDirTraverser | |
28 | { | |
29 | public: | |
30 | wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } | |
31 | ||
32 | virtual wxDirTraverseResult OnFile(const wxString& filename) | |
33 | { | |
34 | m_files.Add(filename); | |
35 | return wxDIR_CONTINUE; | |
36 | } | |
37 | ||
38 | virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) | |
39 | { | |
40 | return wxDIR_CONTINUE; | |
41 | } | |
42 | ||
43 | private: | |
44 | wxArrayString& m_files; | |
45 | }; | |
46 | ||
47 | // get the names of all files in the array | |
48 | wxArrayString files; | |
49 | wxDirTraverserSimple traverser(files); | |
50 | ||
51 | wxDir dir(dirname); | |
52 | dir.Traverse(traverser); | |
53 | @endcode | |
54 | ||
55 | @library{wxbase} | |
56 | @category{file} | |
57 | */ | |
58 | class wxDirTraverser | |
59 | { | |
60 | public: | |
61 | /** | |
62 | This function is called for each directory. It may return ::wxDIR_STOP | |
63 | to abort traversing completely, ::wxDIR_IGNORE to skip this directory | |
64 | but continue with others or ::wxDIR_CONTINUE to enumerate all files and | |
65 | subdirectories in this directory. | |
66 | ||
67 | This is a pure virtual function and must be implemented in the derived | |
68 | class. | |
69 | */ | |
70 | virtual wxDirTraverseResult OnDir(const wxString& dirname) = 0; | |
71 | ||
72 | /** | |
73 | This function is called for each file. It may return ::wxDIR_STOP to | |
74 | abort traversing (for example, if the file being searched is found) or | |
75 | ::wxDIR_CONTINUE to proceed. | |
76 | ||
77 | This is a pure virtual function and must be implemented in the derived | |
78 | class. | |
79 | */ | |
80 | virtual wxDirTraverseResult OnFile(const wxString& filename) = 0; | |
81 | ||
82 | /** | |
83 | This function is called for each directory which we failed to open for | |
84 | enumerating. It may return ::wxDIR_STOP to abort traversing completely, | |
85 | ::wxDIR_IGNORE to skip this directory but continue with others or | |
86 | ::wxDIR_CONTINUE to retry opening this directory once again. | |
87 | ||
88 | The base class version always returns ::wxDIR_IGNORE. | |
89 | */ | |
90 | virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); | |
91 | }; | |
92 | ||
93 | ||
94 | ||
95 | /** | |
96 | These flags affect the behaviour of GetFirst/GetNext() and Traverse(), | |
97 | determining what types are included in the list of items they produce. | |
98 | */ | |
99 | enum wxDirFlags | |
100 | { | |
101 | wxDIR_FILES = 0x0001, ///< Includes files. | |
102 | wxDIR_DIRS = 0x0002, ///< Includes directories. | |
103 | wxDIR_HIDDEN = 0x0004, ///< Includes hidden files. | |
104 | wxDIR_DOTDOT = 0x0008, ///< Includes "." and "..". | |
105 | ||
106 | /** | |
107 | Don't follow symbolic links during the directory traversal. | |
108 | ||
109 | This flag is ignored under systems not supporting symbolic links (i.e. | |
110 | non-Unix ones). | |
111 | ||
112 | Notice that this flag is @e not included in wxDIR_DEFAULT and so the | |
113 | default behaviour of wxDir::Traverse() is to follow symbolic links, | |
114 | even if they lead outside of the directory being traversed. | |
115 | ||
116 | @since 2.9.5 | |
117 | */ | |
118 | wxDIR_NO_FOLLOW = 0x0010, | |
119 | ||
120 | /** | |
121 | Default directory traversal flags include both files and directories, | |
122 | even hidden. | |
123 | ||
124 | Notice that by default wxDIR_NO_FOLLOW is @e not included, meaning that | |
125 | symbolic links are followed by default. If this is not desired, you | |
126 | must pass that flag explicitly. | |
127 | */ | |
128 | wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN | |
129 | }; | |
130 | ||
131 | /** | |
132 | @class wxDir | |
133 | ||
134 | wxDir is a portable equivalent of Unix open/read/closedir functions which | |
135 | allow enumerating of the files in a directory. wxDir allows to enumerate | |
136 | files as well as directories. | |
137 | ||
138 | wxDir also provides a flexible way to enumerate files recursively using | |
139 | Traverse() or a simpler GetAllFiles() function. | |
140 | ||
141 | Example of use: | |
142 | ||
143 | @code | |
144 | wxDir dir(wxGetCwd()); | |
145 | ||
146 | if ( !dir.IsOpened() ) | |
147 | { | |
148 | // deal with the error here - wxDir would already log an error message | |
149 | // explaining the exact reason of the failure | |
150 | return; | |
151 | } | |
152 | ||
153 | puts("Enumerating object files in current directory:"); | |
154 | ||
155 | wxString filename; | |
156 | ||
157 | bool cont = dir.GetFirst(&filename, filespec, flags); | |
158 | while ( cont ) | |
159 | { | |
160 | printf("%s\n", filename.c_str()); | |
161 | ||
162 | cont = dir.GetNext(&filename); | |
163 | } | |
164 | @endcode | |
165 | ||
166 | @library{wxbase} | |
167 | @category{file} | |
168 | */ | |
169 | class wxDir | |
170 | { | |
171 | public: | |
172 | /** | |
173 | Default constructor, use Open() afterwards. | |
174 | */ | |
175 | wxDir(); | |
176 | /** | |
177 | Opens the directory for enumeration, use IsOpened() to test for errors. | |
178 | */ | |
179 | wxDir(const wxString& dir); | |
180 | ||
181 | /** | |
182 | Destructor cleans up the associated resources by calling Close(). | |
183 | ||
184 | It is not virtual and so this class is not meant to be used | |
185 | polymorphically. | |
186 | */ | |
187 | ~wxDir(); | |
188 | ||
189 | /** | |
190 | Close the directory. | |
191 | ||
192 | The object can't be used after closing it, but Open() may be called | |
193 | again to reopen it later. | |
194 | ||
195 | @since 2.9.5 | |
196 | */ | |
197 | void Close(); | |
198 | ||
199 | /** | |
200 | Test for existence of a directory with the given name. | |
201 | */ | |
202 | static bool Exists(const wxString& dir); | |
203 | ||
204 | /** | |
205 | The function returns the path of the first file matching the given | |
206 | @a filespec or an empty string if there are no files matching it. | |
207 | ||
208 | The @a flags parameter may or may not include ::wxDIR_FILES, the | |
209 | function always behaves as if it were specified. By default, @a flags | |
210 | includes ::wxDIR_DIRS and so the function recurses into the | |
211 | subdirectories but if this flag is not specified, the function | |
212 | restricts the search only to the directory @a dirname itself. | |
213 | See ::wxDirFlags for the list of the possible flags. | |
214 | ||
215 | @see Traverse() | |
216 | */ | |
217 | static wxString FindFirst(const wxString& dirname, | |
218 | const wxString& filespec, | |
219 | int flags = wxDIR_DEFAULT); | |
220 | ||
221 | /** | |
222 | The function appends the names of all the files under directory | |
223 | @a dirname to the array @a files (note that its old content is | |
224 | preserved). Only files matching the @a filespec are taken, with empty | |
225 | spec matching all the files. | |
226 | ||
227 | The @a flags parameter should always include ::wxDIR_FILES or the array | |
228 | would be unchanged and should include ::wxDIR_DIRS flag to recurse into | |
229 | subdirectories (both flags are included in the value by default). | |
230 | See ::wxDirFlags for the list of the possible flags. | |
231 | ||
232 | @return Returns the total number of files found while traversing | |
233 | the directory @a dirname (i.e. the number of entries appended | |
234 | to the @a files array). | |
235 | ||
236 | @see Traverse() | |
237 | */ | |
238 | static size_t GetAllFiles(const wxString& dirname, wxArrayString* files, | |
239 | const wxString& filespec = wxEmptyString, | |
240 | int flags = wxDIR_DEFAULT); | |
241 | ||
242 | /** | |
243 | Start enumerating all files matching @a filespec (or all files if it is | |
244 | empty) and @e flags, return @true on success. | |
245 | See ::wxDirFlags for the list of the possible flags. | |
246 | */ | |
247 | bool GetFirst(wxString* filename, | |
248 | const wxString& filespec = wxEmptyString, | |
249 | int flags = wxDIR_DEFAULT) const; | |
250 | ||
251 | /** | |
252 | Returns the name of the directory itself. | |
253 | ||
254 | The returned string does not have the trailing path separator (slash or | |
255 | backslash). | |
256 | ||
257 | Notice that in spite of this the last character of the returned string | |
258 | can still be the path separator if this directory is the root one. | |
259 | Because of this, don't append @c wxFILE_SEP_PATH to the returned value | |
260 | if you do need a slash-terminated directory name but use | |
261 | GetNameWithSep() instead to avoid having duplicate consecutive slashes. | |
262 | */ | |
263 | wxString GetName() const; | |
264 | ||
265 | /** | |
266 | Returns the name of the directory with the path separator appended. | |
267 | ||
268 | The last character of the returned string is always @c wxFILE_SEP_PATH | |
269 | unless the string is empty, indicating that this directory is invalid. | |
270 | ||
271 | @see GetName() | |
272 | ||
273 | @since 2.9.4 | |
274 | */ | |
275 | wxString GetNameWithSep() const; | |
276 | ||
277 | /** | |
278 | Continue enumerating files which satisfy the criteria specified by the | |
279 | last call to GetFirst(). | |
280 | */ | |
281 | bool GetNext(wxString* filename) const; | |
282 | ||
283 | /** | |
284 | Returns the size (in bytes) of all files recursively found in @c dir or | |
285 | @c wxInvalidSize in case of error. | |
286 | ||
287 | In case it happens that while traversing folders a file's size cannot | |
288 | be read, that file is added to the @a filesSkipped array, if not @NULL, | |
289 | and then skipped. This usually happens with some special folders which | |
290 | are locked by the operating system or by another process. Remember that | |
291 | when the size of @a filesSkipped is not zero, then the returned value | |
292 | is not 100% accurate and, if the skipped files were big, it could be | |
293 | far from real size of the directory. | |
294 | ||
295 | @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace() | |
296 | */ | |
297 | static wxULongLong GetTotalSize(const wxString& dir, | |
298 | wxArrayString* filesSkipped = NULL); | |
299 | ||
300 | /** | |
301 | Returns @true if the directory contains any files matching the given | |
302 | @a filespec. If @a filespec is empty, look for any files at all. In any | |
303 | case, even hidden files are taken into account. | |
304 | */ | |
305 | bool HasFiles(const wxString& filespec = wxEmptyString) const; | |
306 | ||
307 | /** | |
308 | Returns @true if the directory contains any subdirectories (if a non | |
309 | empty @a filespec is given, only check for directories matching it). | |
310 | The hidden subdirectories are taken into account as well. | |
311 | */ | |
312 | bool HasSubDirs(const wxString& dirspec = wxEmptyString) const; | |
313 | ||
314 | /** | |
315 | Returns @true if the directory was successfully opened by a previous | |
316 | call to Open(). | |
317 | */ | |
318 | bool IsOpened() const; | |
319 | ||
320 | /** | |
321 | Creates a directory. | |
322 | ||
323 | This is just an alias for wxFileName::Mkdir(); refer to that function | |
324 | for more info. | |
325 | */ | |
326 | static bool Make(const wxString &dir, int perm = wxS_DIR_DEFAULT, | |
327 | int flags = 0); | |
328 | ||
329 | /** | |
330 | Open the directory for enumerating, returns @true on success or @false | |
331 | if an error occurred. | |
332 | */ | |
333 | bool Open(const wxString& dir); | |
334 | ||
335 | /** | |
336 | Removes a directory. | |
337 | ||
338 | This is just an alias for wxFileName::Rmdir(); refer to that function | |
339 | for more info. | |
340 | */ | |
341 | static bool Remove(const wxString &dir, int flags = 0); | |
342 | ||
343 | /** | |
344 | Enumerate all files and directories under the given directory. | |
345 | ||
346 | If @a flags contains ::wxDIR_DIRS this enumeration is recursive, i.e. | |
347 | all the subdirectories of the given one and the files inside them will | |
348 | be traversed. Otherwise only the files in this directory itself are. | |
349 | ||
350 | If @a flags doesn't contain ::wxDIR_FILES then only subdirectories are | |
351 | examined but not normal files. It doesn't make sense to not specify | |
352 | either ::wxDIR_DIRS or ::wxDIR_FILES and usually both of them should be | |
353 | specified, as is the case by default. | |
354 | ||
355 | For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()" | |
356 | is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called | |
357 | for every file. Depending on the return value, the enumeration may | |
358 | continue or stop. If entering a subdirectory fails, @ref | |
359 | wxDirTraverser::OnOpenError() "sink.OnOpenError()" is called. | |
360 | ||
361 | The function returns the total number of files found or @c "(size_t)-1" | |
362 | on error. | |
363 | ||
364 | See ::wxDirFlags for the full list of the possible flags. | |
365 | ||
366 | @see GetAllFiles() | |
367 | */ | |
368 | size_t Traverse(wxDirTraverser& sink, | |
369 | const wxString& filespec = wxEmptyString, | |
370 | int flags = wxDIR_DEFAULT) const; | |
371 | }; | |
372 |