]>
Commit | Line | Data |
---|---|---|
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 enumerate files as | |
16 | 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 filenames 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 | \latexignore{\rtfignore{\wxheading{Members}}} | |
76 | ||
77 | \membersection{wxDir::Exists}\label{wxdirexists} | |
78 | ||
79 | \func{static bool}{Exists}{\param{const wxString\& }{dir}} | |
80 | ||
81 | Test for existence of a directory with the given name | |
82 | ||
83 | \membersection{wxDir::wxDir}\label{wxdirwxdir} | |
84 | ||
85 | \func{}{wxDir}{\void} | |
86 | ||
87 | Default constructor, use \helpref{Open()}{wxdiropen} afterwards. | |
88 | ||
89 | \func{}{wxDir}{\param{const wxString\& }{dir}} | |
90 | ||
91 | Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened} | |
92 | to test for errors. | |
93 | ||
94 | \membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor} | |
95 | ||
96 | \func{}{\destruct{wxDir}}{\void} | |
97 | ||
98 | Destructor cleans up the associated ressources. It is not virtual and so this | |
99 | class is not meant to be used polymorphically. | |
100 | ||
101 | \membersection{wxDir::Open}\label{wxdiropen} | |
102 | ||
103 | \func{bool}{Open}{\param{const wxString\& }{dir}} | |
104 | ||
105 | Open the directory for enumerating, returns TRUE on success or FALSE if an | |
106 | error occurred. | |
107 | ||
108 | \membersection{wxDir::IsOpened}\label{wxdirisopened} | |
109 | ||
110 | \constfunc{bool}{IsOpened}{\void} | |
111 | ||
112 | Returns 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 | ||
119 | Start enumerating all files matching {\it filespec} (or all files if it is | |
120 | empty) and flags, return TRUE on success. | |
121 | ||
122 | \membersection{wxDir::GetNext}\label{wxdirgetnext} | |
123 | ||
124 | \constfunc{bool}{GetNext}{\param{wxString* }{filename}} | |
125 | ||
126 | Continue enumerating files satisfying the criteria specified by the last call | |
127 | to \helpref{GetFirst}{wxdirgetfirst}. | |
128 | ||
129 | \membersection{wxDir::HasFiles}\label{wxdirhasfiles} | |
130 | ||
131 | \func{bool}{HasFiles}{\param{const wxString& }{filespec = wxEmptyString}} | |
132 | ||
133 | Returns {\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 | |
135 | case, 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 | ||
141 | Returns {\tt TRUE} if the directory contains any subdirectories (if a non | |
142 | empty {\it filespec} is given, only check for directories matching it). | |
143 | The 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 | ||
149 | Enumerate all files and directories under the given directory recursively | |
150 | calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser} | |
151 | object for each of them. | |
152 | ||
153 | More precisely, the function will really recurse into subdirectories if | |
154 | {\it flags} contains {\tt wxDIR\_DIRS} flag. It will ignore the files (but | |
155 | still possibly recurse into subdirectories) if {\tt wxDIR\_FILES} flag is | |
156 | given. | |
157 | ||
158 | For each found directory, \helpref{sink.OnDir()}{wxdirtraverserondir} is called | |
159 | and \helpref{sink.OnFile()}{wxdirtraverseronfile} is called for every file. | |
160 | Depending on the return value, the enumeration may continue or stop. | |
161 | ||
162 | The function returns the total number of files found or {\tt (size\_t)-1} on | |
163 | error. | |
164 | ||
165 | See 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 | ||
171 | The function appends the names of all the files under directory {\it dirname} | |
172 | to the array {\it files} (note that its old contents is preserved). Only files | |
173 | matching the {\it filespec} are taken, with empty spec matching all the files. | |
174 | ||
175 | The {\it flags} parameter should always include {\tt wxDIR\_FILES} or the array | |
176 | would be unchanged and should include {\tt wxDIR\_DIRS} flag to recurse into | |
177 | subdirectories (both flags are included in the value by default). | |
178 | ||
179 | See also: \helpref{Traverse}{wxdirtraverse} | |
180 | ||
181 | \section{\class{wxDirTraverser}}\label{wxdirtraverser} | |
182 | ||
183 | wxDirTraverser is an abstract interface which must be implemented by objects | |
184 | passed to \helpref{Traverse}{wxdirtraverse} function. | |
185 | ||
186 | Example 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 | ||
219 | No base class | |
220 | ||
221 | \wxheading{Constants} | |
222 | ||
223 | The elements of {\tt wxDirTraverseResult} are the possible return values of the | |
224 | callback functions: | |
225 | ||
226 | {\small | |
227 | \begin{verbatim} | |
228 | enum 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 | ||
247 | This function is called for each file. It may return {\tt wxDIR\_STOP} to abort | |
248 | traversing (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 | ||
255 | This function is called for each directory. It may return {\tt wxSIR\_STOP} | |
256 | to abort traversing completely, {\tt wxDIR\_IGNORE} to skip this directory but | |
257 | continue with others or {\tt wxDIR\_CONTINUE} to enumerate all files and | |
258 | subdirectories in this directory. | |
259 |