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