]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/dir.tex
Fixed to work with the new wxMacControl system.
[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: wxWidgets 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 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 contents 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::GetFirst}\label{wxdirgetfirst}
120
121\constfunc{bool}{GetFirst}{\param{wxString* }{filename}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
122
123Start enumerating all files matching {\it filespec} (or all files if it is
124empty) and flags, return true on success.
125
126
127\membersection{wxDir::GetName}\label{wxdirgetname}
128
129\constfunc{wxString}{GetName}{\void}
130
131Returns the name of the directory itself. The returned string does not have the
132trailing path separator (slash or backslash).
133
134
135\membersection{wxDir::GetNext}\label{wxdirgetnext}
136
137\constfunc{bool}{GetNext}{\param{wxString* }{filename}}
138
139Continue enumerating files satisfying the criteria specified by the last call
140to \helpref{GetFirst}{wxdirgetfirst}.
141
142
143\membersection{wxDir::HasFiles}\label{wxdirhasfiles}
144
145\func{bool}{HasFiles}{\param{const wxString\& }{filespec = wxEmptyString}}
146
147Returns {\tt true} if the directory contains any files matching the given
148{\it filespec}. If {\it filespec} is empty, look for any files at all. In any
149case, even hidden files are taken into account.
150
151
152\membersection{wxDir::HasSubDirs}\label{wxdirhassubdirs}
153
154\func{bool}{HasSubDirs}{\param{const wxString\& }{dirspec = wxEmptyString}}
155
156Returns {\tt true} if the directory contains any subdirectories (if a non
157empty {\it filespec} is given, only check for directories matching it).
158The hidden subdirectories are taken into account as well.
159
160
161\membersection{wxDir::IsOpened}\label{wxdirisopened}
162
163\constfunc{bool}{IsOpened}{\void}
164
165Returns true if the directory was successfully opened by a previous call to
166\helpref{Open}{wxdiropen}.
167
168
169\membersection{wxDir::Open}\label{wxdiropen}
170
171\func{bool}{Open}{\param{const wxString\& }{dir}}
172
173Open the directory for enumerating, returns true on success or false if an
174error occurred.
175
176
177\membersection{wxDir::Traverse}\label{wxdirtraverse}
178
179\func{size\_t}{Traverse}{\param{wxDirTraverser\& }{sink}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
180
181Enumerate all files and directories under the given directory recursively
182calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser}
183object for each of them.
184
185More precisely, the function will really recurse into subdirectories if
186{\it flags} contains {\tt wxDIR\_DIRS} flag. It will ignore the files (but
187still possibly recurse into subdirectories) if {\tt wxDIR\_FILES} flag is
188given.
189
190For each found directory, \helpref{sink.OnDir()}{wxdirtraverserondir} is called
191and \helpref{sink.OnFile()}{wxdirtraverseronfile} is called for every file.
192Depending on the return value, the enumeration may continue or stop.
193
194The function returns the total number of files found or {\tt (size\_t)-1} on
195error.
196
197See also: \helpref{GetAllFiles}{wxdirgetallfiles}
198