]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/dir.tex
interface headers reviewed
[wxWidgets.git] / docs / latex / wx / dir.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: dir.tex
3 %% Purpose: wxDir documentation
4 %% Author: Vadim Zeitlin
5 %% Modified by:
6 %% Created: 04.04.00
7 %% RCS-ID: $Id$
8 %% Copyright: (c) Vadim Zeitlin
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxDir}}\label{wxdir}
13
14 wxDir is a portable equivalent of Unix {open/read/close}dir functions which
15 allow enumerating of the files in a directory. wxDir allows to enumerate files
16 as well as directories.
17
18 wxDir also provides a flexible way to enumerate files recursively using
19 \helpref{Traverse}{wxdirtraverse} or a simpler
20 \helpref{GetAllFiles}{wxdirgetallfiles} function.
21
22 Example of use:
23
24 \begin{verbatim}
25 wxDir dir(wxGetCwd());
26
27 if ( !dir.IsOpened() )
28 {
29 // deal with the error here - wxDir would already log an error message
30 // explaining the exact reason of the failure
31 return;
32 }
33
34 puts("Enumerating object files in current directory:");
35
36 wxString filename;
37
38 bool cont = dir.GetFirst(&filename, filespec, flags);
39 while ( cont )
40 {
41 printf("%s\n", filename.c_str());
42
43 cont = dir.GetNext(&filename);
44 }
45 \end{verbatim}
46
47 \wxheading{Derived from}
48
49 No base class
50
51 \wxheading{Constants}
52
53 These flags define what kind of filename is included in the list of files
54 enumerated by GetFirst/GetNext.
55
56 {\small
57 \begin{verbatim}
58 enum
59 {
60 wxDIR_FILES = 0x0001, // include files
61 wxDIR_DIRS = 0x0002, // include directories
62 wxDIR_HIDDEN = 0x0004, // include hidden files
63 wxDIR_DOTDOT = 0x0008, // include '.' and '..'
64
65 // by default, enumerate everything except '.' and '..'
66 wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
67 }
68 \end{verbatim}
69 }
70
71 \wxheading{Include files}
72
73 <wx/dir.h>
74
75 \wxheading{Library}
76
77 \helpref{wxBase}{librarieslist}
78
79 \latexignore{\rtfignore{\wxheading{Members}}}
80
81 \membersection{wxDir::wxDir}\label{wxdirwxdir}
82
83 \func{}{wxDir}{\void}
84
85 Default constructor, use \helpref{Open()}{wxdiropen} afterwards.
86
87 \func{}{wxDir}{\param{const wxString\& }{dir}}
88
89 Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened}
90 to test for errors.
91
92
93 \membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor}
94
95 \func{}{\destruct{wxDir}}{\void}
96
97 Destructor cleans up the associated resources. It is not virtual and so this
98 class is not meant to be used polymorphically.
99
100
101 \membersection{wxDir::Exists}\label{wxdirexists}
102
103 \func{static bool}{Exists}{\param{const wxString\& }{dir}}
104
105 Test for existence of a directory with the given name
106
107
108 \membersection{wxDir::GetAllFiles}\label{wxdirgetallfiles}
109
110 \func{static size\_t}{GetAllFiles}{\param{const wxString\& }{dirname}, \param{wxArrayString *}{files}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
111
112 The function appends the names of all the files under directory {\it dirname}
113 to the array {\it files} (note that its old content is preserved). Only files
114 matching the {\it filespec} are taken, with empty spec matching all the files.
115
116 The {\it flags} parameter should always include {\tt wxDIR\_FILES} or the array
117 would be unchanged and should include {\tt wxDIR\_DIRS} flag to recurse into
118 subdirectories (both flags are included in the value by default).
119
120 See also: \helpref{Traverse}{wxdirtraverse}
121
122
123 \membersection{wxDir::FindFirst}\label{wxdirfindfirst}
124
125 \func{static wxString}{FindFirst}{\param{const wxString\& }{dirname}, \param{const wxString\& }{filespec}, \param{int }{flags = wxDIR\_DEFAULT}}
126
127 The function returns the path of the first file matching the given \arg{filespec}
128 or an empty string if there are no files matching it.
129
130 The \arg{flags} parameter may or may not include {\tt wxDIR\_FILES}, the
131 function always behaves as if it were specified. By default, \arg{flags}
132 includes {\tt wxDIR\_DIRS} and so the function recurses into the subdirectories
133 but if this flag is not specified, the function restricts the search only to
134 the directory \arg{dirname} itself.
135
136 See also: \helpref{Traverse}{wxdirtraverse}
137
138
139 \membersection{wxDir::GetFirst}\label{wxdirgetfirst}
140
141 \constfunc{bool}{GetFirst}{\param{wxString* }{filename}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
142
143 Start enumerating all files matching {\it filespec} (or all files if it is
144 empty) and {\it flags}, return \true on success.
145
146
147 \membersection{wxDir::GetName}\label{wxdirgetname}
148
149 \constfunc{wxString}{GetName}{\void}
150
151 Returns the name of the directory itself. The returned string does not have the
152 trailing path separator (slash or backslash).
153
154
155 \membersection{wxDir::GetNext}\label{wxdirgetnext}
156
157 \constfunc{bool}{GetNext}{\param{wxString* }{filename}}
158
159 Continue enumerating files which satisfy the criteria specified by the last
160 call to \helpref{GetFirst}{wxdirgetfirst}.
161
162
163 \membersection{wxDir::GetTotalSize}\label{wxdirgettotalsize}
164
165 \func{static wxULongLong}{GetTotalSize}{\param{const wxString\& }{dir}, \param{wxArrayString* }{filesSkipped = NULL}}
166
167 Returns the size (in bytes) of all files recursively found in {\tt dir} or
168 {\tt wxInvalidSize} in case of error.
169
170 In case it happens that while traversing folders a file's size can not be read,
171 that file is added to the {\tt filesSkipped} array, if not \NULL, and then
172 skipped.
173 This usually happens with some special folders which are locked by the operating system
174 or by another process. Remember that when {\tt filesSkipped->GetCount()} is not zero,
175 then the returned value is not 100\% accurate and, if the skipped files were big, it could be
176 far from real size of the directory.
177
178 See also: \helpref{wxFileName::GetHumanReadableSize}{wxfilenamegethumanreadablesize},
179 \helpref{wxGetDiskSpace}{wxgetdiskspace}
180
181
182 \membersection{wxDir::HasFiles}\label{wxdirhasfiles}
183
184 \func{bool}{HasFiles}{\param{const wxString\& }{filespec = wxEmptyString}}
185
186 Returns {\tt true} if the directory contains any files matching the given
187 {\it filespec}. If {\it filespec} is empty, look for any files at all. In any
188 case, even hidden files are taken into account.
189
190
191 \membersection{wxDir::HasSubDirs}\label{wxdirhassubdirs}
192
193 \func{bool}{HasSubDirs}{\param{const wxString\& }{dirspec = wxEmptyString}}
194
195 Returns {\tt true} if the directory contains any subdirectories (if a non
196 empty {\it filespec} is given, only check for directories matching it).
197 The hidden subdirectories are taken into account as well.
198
199
200 \membersection{wxDir::IsOpened}\label{wxdirisopened}
201
202 \constfunc{bool}{IsOpened}{\void}
203
204 Returns true if the directory was successfully opened by a previous call to
205 \helpref{Open}{wxdiropen}.
206
207
208 \membersection{wxDir::Open}\label{wxdiropen}
209
210 \func{bool}{Open}{\param{const wxString\& }{dir}}
211
212 Open the directory for enumerating, returns {\tt true} on success
213 or {\tt false} if an error occurred.
214
215
216 \membersection{wxDir::Traverse}\label{wxdirtraverse}
217
218 \func{size\_t}{Traverse}{\param{wxDirTraverser\& }{sink}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
219
220 Enumerate all files and directories under the given directory recursively
221 calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser}
222 object for each of them.
223
224 More precisely, the function will really recurse into subdirectories if
225 {\it flags} contains {\tt wxDIR\_DIRS} flag. It will ignore the files (but
226 still possibly recurse into subdirectories) if {\tt wxDIR\_FILES} flag is
227 given.
228
229 For each found directory, \helpref{sink.OnDir()}{wxdirtraverserondir} is called
230 and \helpref{sink.OnFile()}{wxdirtraverseronfile} is called for every file.
231 Depending on the return value, the enumeration may continue or stop.
232
233 The function returns the total number of files found or {\tt (size\_t)-1} on
234 error.
235
236 See also: \helpref{GetAllFiles}{wxdirgetallfiles}
237