]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/dir.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDir and wxDirTraverser
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 Possible return values of wxDirTraverser callback functions.
12 enum wxDirTraverseResult
14 wxDIR_IGNORE
= -1, ///< Ignore this directory but continue with others.
15 wxDIR_STOP
, ///< Stop traversing.
16 wxDIR_CONTINUE
///< Continue into this directory.
22 wxDirTraverser is an abstract interface which must be implemented by
23 objects passed to wxDir::Traverse() function.
25 Example of use (this works almost like wxDir::GetAllFiles()):
28 class wxDirTraverserSimple : public wxDirTraverser
31 wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
33 virtual wxDirTraverseResult OnFile(const wxString& filename)
35 m_files.Add(filename);
36 return wxDIR_CONTINUE;
39 virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
41 return wxDIR_CONTINUE;
45 wxArrayString& m_files;
48 // get the names of all files in the array
50 wxDirTraverserSimple traverser(files);
53 dir.Traverse(traverser);
63 This function is called for each directory. It may return ::wxDIR_STOP
64 to abort traversing completely, ::wxDIR_IGNORE to skip this directory
65 but continue with others or ::wxDIR_CONTINUE to enumerate all files and
66 subdirectories in this directory.
68 This is a pure virtual function and must be implemented in the derived
71 virtual wxDirTraverseResult
OnDir(const wxString
& dirname
) = 0;
74 This function is called for each file. It may return ::wxDIR_STOP to
75 abort traversing (for example, if the file being searched is found) or
76 ::wxDIR_CONTINUE to proceed.
78 This is a pure virtual function and must be implemented in the derived
81 virtual wxDirTraverseResult
OnFile(const wxString
& filename
) = 0;
84 This function is called for each directory which we failed to open for
85 enumerating. It may return ::wxDIR_STOP to abort traversing completely,
86 ::wxDIR_IGNORE to skip this directory but continue with others or
87 ::wxDIR_CONTINUE to retry opening this directory once again.
89 The base class version always returns ::wxDIR_IGNORE.
91 virtual wxDirTraverseResult
OnOpenError(const wxString
& openerrorname
);
97 These flags define what kind of filenames are included in the list of files
98 enumerated by wxDir::GetFirst() and wxDir::GetNext().
102 wxDIR_FILES
= 0x0001, ///< Includes files.
103 wxDIR_DIRS
= 0x0002, ///< Includes directories.
104 wxDIR_HIDDEN
= 0x0004, ///< Includes hidden files.
105 wxDIR_DOTDOT
= 0x0008, ///< Includes "." and "..".
107 //! Combination of the @c wxDIR_FILES, @c wxDIR_DIRS, @c wxDIR_HIDDEN flags
109 wxDIR_DEFAULT
= wxDIR_FILES
| wxDIR_DIRS
| wxDIR_HIDDEN
115 wxDir is a portable equivalent of Unix open/read/closedir functions which
116 allow enumerating of the files in a directory. wxDir allows to enumerate
117 files as well as directories.
119 wxDir also provides a flexible way to enumerate files recursively using
120 Traverse() or a simpler GetAllFiles() function.
125 wxDir dir(wxGetCwd());
127 if ( !dir.IsOpened() )
129 // deal with the error here - wxDir would already log an error message
130 // explaining the exact reason of the failure
134 puts("Enumerating object files in current directory:");
138 bool cont = dir.GetFirst(&filename, filespec, flags);
141 printf("%s\n", filename.c_str());
143 cont = dir.GetNext(&filename);
154 Default constructor, use Open() afterwards.
158 Opens the directory for enumeration, use IsOpened() to test for errors.
160 wxDir(const wxString
& dir
);
163 Destructor cleans up the associated resources. It is not virtual and so
164 this class is not meant to be used polymorphically.
169 Test for existence of a directory with the given name.
171 static bool Exists(const wxString
& dir
);
174 The function returns the path of the first file matching the given
175 @a filespec or an empty string if there are no files matching it.
177 The @a flags parameter may or may not include ::wxDIR_FILES, the
178 function always behaves as if it were specified. By default, @a flags
179 includes ::wxDIR_DIRS and so the function recurses into the
180 subdirectories but if this flag is not specified, the function
181 restricts the search only to the directory @a dirname itself.
182 See ::wxDirFlags for the list of the possible flags.
186 static wxString
FindFirst(const wxString
& dirname
,
187 const wxString
& filespec
,
188 int flags
= wxDIR_DEFAULT
);
191 The function appends the names of all the files under directory
192 @a dirname to the array @a files (note that its old content is
193 preserved). Only files matching the @a filespec are taken, with empty
194 spec matching all the files.
196 The @a flags parameter should always include ::wxDIR_FILES or the array
197 would be unchanged and should include ::wxDIR_DIRS flag to recurse into
198 subdirectories (both flags are included in the value by default).
199 See ::wxDirFlags for the list of the possible flags.
201 @return Returns the total number of files found while traversing
202 the directory @a dirname (i.e. the number of entries appended
203 to the @a files array).
207 static size_t GetAllFiles(const wxString
& dirname
, wxArrayString
* files
,
208 const wxString
& filespec
= wxEmptyString
,
209 int flags
= wxDIR_DEFAULT
);
212 Start enumerating all files matching @a filespec (or all files if it is
213 empty) and @e flags, return @true on success.
214 See ::wxDirFlags for the list of the possible flags.
216 bool GetFirst(wxString
* filename
,
217 const wxString
& filespec
= wxEmptyString
,
218 int flags
= wxDIR_DEFAULT
) const;
221 Returns the name of the directory itself.
223 The returned string does not have the trailing path separator (slash or
226 Notice that in spite of this the last character of the returned string
227 can still be the path separator if this directory is the root one.
228 Because of this, don't append ::wxFILE_SEP_PATH to the returned value
229 if you do need a slash-terminated directory name but use
230 GetNameWithSep() instead to avoid having duplicate consecutive slashes.
232 wxString
GetName() const;
235 Returns the name of the directory with the path separator appended.
237 The last character of the returned string is always ::wxFILE_SEP_PATH
238 unless the string is empty, indicating that this directory is invalid.
244 wxString
GetNameWithSep() const;
247 Continue enumerating files which satisfy the criteria specified by the
248 last call to GetFirst().
250 bool GetNext(wxString
* filename
) const;
253 Returns the size (in bytes) of all files recursively found in @c dir or
254 @c wxInvalidSize in case of error.
256 In case it happens that while traversing folders a file's size cannot
257 be read, that file is added to the @a filesSkipped array, if not @NULL,
258 and then skipped. This usually happens with some special folders which
259 are locked by the operating system or by another process. Remember that
260 when the size of @a filesSkipped is not zero, then the returned value
261 is not 100% accurate and, if the skipped files were big, it could be
262 far from real size of the directory.
264 @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
266 static wxULongLong
GetTotalSize(const wxString
& dir
,
267 wxArrayString
* filesSkipped
= NULL
);
270 Returns @true if the directory contains any files matching the given
271 @a filespec. If @a filespec is empty, look for any files at all. In any
272 case, even hidden files are taken into account.
274 bool HasFiles(const wxString
& filespec
= wxEmptyString
) const;
277 Returns @true if the directory contains any subdirectories (if a non
278 empty @a filespec is given, only check for directories matching it).
279 The hidden subdirectories are taken into account as well.
281 bool HasSubDirs(const wxString
& dirspec
= wxEmptyString
) const;
284 Returns @true if the directory was successfully opened by a previous
287 bool IsOpened() const;
292 This is just an alias for wxFileName::Mkdir(); refer to that function
295 static bool Make(const wxString
&dir
, int perm
= wxS_DIR_DEFAULT
,
299 Open the directory for enumerating, returns @true on success or @false
300 if an error occurred.
302 bool Open(const wxString
& dir
);
307 This is just an alias for wxFileName::Rmdir(); refer to that function
310 static bool Remove(const wxString
&dir
, int flags
= 0);
313 Enumerate all files and directories under the given directory
314 recursively calling the element of the provided wxDirTraverser object
317 More precisely, the function will really recurse into subdirectories if
318 @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but
319 still possibly recurse into subdirectories) if ::wxDIR_FILES flag is
321 See ::wxDirFlags for the list of the possible flags.
323 For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()"
324 is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
325 for every file. Depending on the return value, the enumeration may
328 The function returns the total number of files found or @c "(size_t)-1"
333 size_t Traverse(wxDirTraverser
& sink
,
334 const wxString
& filespec
= wxEmptyString
,
335 int flags
= wxDIR_DEFAULT
) const;