| 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 to enumerate files |
| 16 | as 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 filename 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::wxDir}\label{wxdirwxdir} |
| 78 | |
| 79 | \func{}{wxDir}{\void} |
| 80 | |
| 81 | Default constructor, use \helpref{Open()}{wxdiropen} afterwards. |
| 82 | |
| 83 | \func{}{wxDir}{\param{const wxString\& }{dir}} |
| 84 | |
| 85 | Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened} |
| 86 | to test for errors. |
| 87 | |
| 88 | |
| 89 | \membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor} |
| 90 | |
| 91 | \func{}{\destruct{wxDir}}{\void} |
| 92 | |
| 93 | Destructor cleans up the associated resources. It is not virtual and so this |
| 94 | class 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 | |
| 101 | Test 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 | |
| 108 | The function appends the names of all the files under directory {\it dirname} |
| 109 | to the array {\it files} (note that its old content is preserved). Only files |
| 110 | matching the {\it filespec} are taken, with empty spec matching all the files. |
| 111 | |
| 112 | The {\it flags} parameter should always include {\tt wxDIR\_FILES} or the array |
| 113 | would be unchanged and should include {\tt wxDIR\_DIRS} flag to recurse into |
| 114 | subdirectories (both flags are included in the value by default). |
| 115 | |
| 116 | See 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 | |
| 123 | The function returns the path of the first file matching the given \arg{filespec} |
| 124 | or an empty string if there are no files matching it. |
| 125 | |
| 126 | The \arg{flags} parameter may or may not include {\tt wxDIR\_FILES}, the |
| 127 | function always behaves as if it were specified. By default, \arg{flags} |
| 128 | includes {\tt wxDIR\_DIRS} and so the function recurses into the subdirectories |
| 129 | but if this flag is not specified, the function restricts the search only to |
| 130 | the directory \arg{dirname} itself. |
| 131 | |
| 132 | See 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 | |
| 139 | Start enumerating all files matching {\it filespec} (or all files if it is |
| 140 | empty) and {\it flags}, return \true on success. |
| 141 | |
| 142 | |
| 143 | \membersection{wxDir::GetName}\label{wxdirgetname} |
| 144 | |
| 145 | \constfunc{wxString}{GetName}{\void} |
| 146 | |
| 147 | Returns the name of the directory itself. The returned string does not have the |
| 148 | trailing path separator (slash or backslash). |
| 149 | |
| 150 | |
| 151 | \membersection{wxDir::GetNext}\label{wxdirgetnext} |
| 152 | |
| 153 | \constfunc{bool}{GetNext}{\param{wxString* }{filename}} |
| 154 | |
| 155 | Continue enumerating files which satisfy the criteria specified by the last |
| 156 | call 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 | |
| 163 | Returns the size (in bytes) of all files recursively found in {\tt dir} or |
| 164 | {\tt wxInvalidSize} in case of error. |
| 165 | |
| 166 | In case it happens that while traversing folders a file's size can not be read, |
| 167 | that file is added to the {\tt filesSkipped} array, if not \NULL, and then |
| 168 | skipped. |
| 169 | This usually happens with some special folders which are locked by the operating system |
| 170 | or by another process. Remember that when {\tt filesSkipped->GetCount()} is not zero, |
| 171 | then the returned value is not 100\% accurate and, if the skipped files were big, it could be |
| 172 | far from real size of the directory. |
| 173 | |
| 174 | See 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 | |
| 182 | Returns {\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 |
| 184 | case, 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 | |
| 191 | Returns {\tt true} if the directory contains any subdirectories (if a non |
| 192 | empty {\it filespec} is given, only check for directories matching it). |
| 193 | The hidden subdirectories are taken into account as well. |
| 194 | |
| 195 | |
| 196 | \membersection{wxDir::IsOpened}\label{wxdirisopened} |
| 197 | |
| 198 | \constfunc{bool}{IsOpened}{\void} |
| 199 | |
| 200 | Returns 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 | |
| 208 | Open the directory for enumerating, returns {\tt true} on success |
| 209 | or {\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 | |
| 216 | Enumerate all files and directories under the given directory recursively |
| 217 | calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser} |
| 218 | object for each of them. |
| 219 | |
| 220 | More precisely, the function will really recurse into subdirectories if |
| 221 | {\it flags} contains {\tt wxDIR\_DIRS} flag. It will ignore the files (but |
| 222 | still possibly recurse into subdirectories) if {\tt wxDIR\_FILES} flag is |
| 223 | given. |
| 224 | |
| 225 | For each found directory, \helpref{sink.OnDir()}{wxdirtraverserondir} is called |
| 226 | and \helpref{sink.OnFile()}{wxdirtraverseronfile} is called for every file. |
| 227 | Depending on the return value, the enumeration may continue or stop. |
| 228 | |
| 229 | The function returns the total number of files found or {\tt (size\_t)-1} on |
| 230 | error. |
| 231 | |
| 232 | See also: \helpref{GetAllFiles}{wxdirgetallfiles} |
| 233 | |