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