]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/dir.tex
Removed Aqua style from docs.
[wxWidgets.git] / docs / latex / wx / dir.tex
... / ...
CommitLineData
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
14wxDir is a portable equivalent of Unix {open/read/close}dir functions which
15allow enumerating of the files in a directory. wxDir allows enumerate files as
16well 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 filenames 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::Exists}\label{wxdirexists}
78
79\func{static bool}{Exists}{\param{const wxString\& }{dir}}
80
81Test for existence of a directory with the given name
82
83\membersection{wxDir::wxDir}\label{wxdirwxdir}
84
85\func{}{wxDir}{\void}
86
87Default constructor, use \helpref{Open()}{wxdiropen} afterwards.
88
89\func{}{wxDir}{\param{const wxString\& }{dir}}
90
91Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened}
92to test for errors.
93
94\membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor}
95
96\func{}{\destruct{wxDir}}{\void}
97
98Destructor cleans up the associated ressources. It is not virtual and so this
99class is not meant to be used polymorphically.
100
101\membersection{wxDir::Open}\label{wxdiropen}
102
103\func{bool}{Open}{\param{const wxString\& }{dir}}
104
105Open the directory for enumerating, returns TRUE on success or FALSE if an
106error occurred.
107
108\membersection{wxDir::IsOpened}\label{wxdirisopened}
109
110\constfunc{bool}{IsOpened}{\void}
111
112Returns TRUE if the directory was successfully opened by a previous call to
113\helpref{Open}{wxdiropen}.
114
115\membersection{wxDir::GetFirst}\label{wxdirgetfirst}
116
117\constfunc{bool}{GetFirst}{\param{wxString* }{filename}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
118
119Start enumerating all files matching {\it filespec} (or all files if it is
120empty) and flags, return TRUE on success.
121
122\membersection{wxDir::GetNext}\label{wxdirgetnext}
123
124\constfunc{bool}{GetNext}{\param{wxString* }{filename}}
125
126Continue enumerating files satisfying the criteria specified by the last call
127to \helpref{GetFirst}{wxdirgetfirst}.
128
129\membersection{wxDir::HasFiles}\label{wxdirhasfiles}
130
131\func{bool}{HasFiles}{\param{const wxString& }{filespec = wxEmptyString}}
132
133Returns {\tt TRUE} if the directory contains any files matching the given
134{\it filespec}. If {\it filespec} is empty, look for any files at all. In any
135case, even hidden files are taken into account.
136
137\membersection{wxDir::HasSubDirs}\label{wxdirhassubdirs}
138
139\func{bool}{HasSubDirs}{\param{const wxString& }{dirspec = wxEmptyString}}
140
141Returns {\tt TRUE} if the directory contains any subdirectories (if a non
142empty {\it filespec} is given, only check for directories matching it).
143The hidden subdirectories are taken into account as well.
144
145\membersection{wxDir::Traverse}\label{wxdirtraverse}
146
147\func{size\_t}{Traverse}{\param{wxDirTraverser& }{sink}, \param{const wxString& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
148
149Enumerate all files and directories under the given directory recursively
150calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser}
151object for each of them.
152
153More precisely, the function will really recurse into subdirectories if
154{\it flags} contains {\tt wxDIR\_DIRS} flag. It will ignore the files (but
155still possibly recurse into subdirectories) if {\tt wxDIR\_FILES} flag is
156given.
157
158For each found directory, \helpref{sink.OnDir()}{wxdirtraverserondir} is called
159and \helpref{sink.OnFile()}{wxdirtraverseronfile} is called for every file.
160Depending on the return value, the enumeration may continue or stop.
161
162The function returns the total number of files found or {\tt (size\_t)-1} on
163error.
164
165See also: \helpref{GetAllFiles}{wxdirgetallfiles}
166
167\membersection{wxDir::GetAllFiles}\label{wxdirgetallfiles}
168
169\func{static size\_t}{GetAllFiles}{\param{const wxString& }{dirname}, \param{wxArrayString *}{files}, \param{const wxString& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
170
171The function appends the names of all the files under directory {\it dirname}
172to the array {\it files} (note that its old contents is preserved). Only files
173matching the {\it filespec} are taken, with empty spec matching all the files.
174
175The {\it flags} parameter should always include {\tt wxDIR\_FILES} or the array
176would be unchanged and should include {\tt wxDIR\_DIRS} flag to recurse into
177subdirectories (both flags are included in the value by default).
178
179See also: \helpref{Traverse}{wxdirtraverse}
180
181\section{\class{wxDirTraverser}}\label{wxdirtraverser}
182
183wxDirTraverser is an abstract interface which must be implemented by objects
184passed to \helpref{Traverse}{wxdirtraverse} function.
185
186Example of use (this works almost like \helpref{GetAllFiles}{wxdirgetallfiles}):
187
188\begin{verbatim}
189 class wxDirTraverserSimple : public wxDirTraverser
190 {
191 public:
192 wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
193
194 virtual wxDirTraverseResult OnFile(const wxString& filename)
195 {
196 m_files.Add(filename);
197 return wxDIR_CONTINUE;
198 }
199
200 virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
201 {
202 return wxDIR_CONTINUE;
203 }
204
205 private:
206 wxArrayString& m_files;
207 };
208
209 // get the names of all files in the array
210 wxArrayString files;
211 wxDirTraverserSimple traverser(files);
212
213 wxDir dir(dirname);
214 dir.Traverse(traverser);
215\end{verbatim}
216
217\wxheading{Derived from}
218
219No base class
220
221\wxheading{Constants}
222
223The elements of {\tt wxDirTraverseResult} are the possible return values of the
224callback functions:
225
226{\small
227\begin{verbatim}
228enum wxDirTraverseResult
229{
230 wxDIR_IGNORE = -1, // ignore this directory but continue with others
231 wxDIR_STOP, // stop traversing
232 wxDIR_CONTINUE // continue into this directory
233};
234\end{verbatim}
235}
236
237\wxheading{Include files}
238
239<wx/dir.h>
240
241\latexignore{\rtfignore{\wxheading{Members}}}
242
243\membersection{wxDirTraverser::OnFile}\label{wxdirtraverseronfile}
244
245\func{virtual wxDirTraverseResult}{OnFile}{\param{const wxString& }{filename}}
246
247This function is called for each file. It may return {\tt wxDIR\_STOP} to abort
248traversing (for example, if the file being searched is found) or
249{\tt wxDIR\_CONTINUE} to proceed.
250
251\membersection{wxDirTraverser::OnDir}\label{wxdirtraverserondir}
252
253\func{virtual wxDirTraverseResult}{OnDir}{\param{const wxString& }{dirname}}
254
255This function is called for each directory. It may return {\tt wxSIR\_STOP}
256to abort traversing completely, {\tt wxDIR\_IGNORE} to skip this directory but
257continue with others or {\tt wxDIR\_CONTINUE} to enumerate all files and
258subdirectories in this directory.
259