]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/dir.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / dir.h
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