docs/latex/wx/dir.tex

   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 \wxheading{Library}
  76
  77 \helpref{wxBase}{librarieslist}
  78
  79 \latexignore{\rtfignore{\wxheading{Members}}}
  80
  81 \membersection{wxDir::wxDir}\label{wxdirwxdir}
  82
  83 \func{}{wxDir}{\void}
  84
  85 Default constructor, use \helpref{Open()}{wxdiropen} afterwards.
  86
  87 \func{}{wxDir}{\param{const wxString\& }{dir}}
  88
  89 Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened}
  90 to test for errors.
  91
  92
  93 \membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor}
  94
  95 \func{}{\destruct{wxDir}}{\void}
  96
  97 Destructor cleans up the associated resources. It is not virtual and so this
  98 class is not meant to be used polymorphically.
  99
 100
 101 \membersection{wxDir::Exists}\label{wxdirexists}
 102
 103 \func{static bool}{Exists}{\param{const wxString\& }{dir}}
 104
 105 Test for existence of a directory with the given name
 106
 107
 108 \membersection{wxDir::GetAllFiles}\label{wxdirgetallfiles}
 109
 110 \func{static size\_t}{GetAllFiles}{\param{const wxString\& }{dirname}, \param{wxArrayString *}{files}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
 111
 112 The function appends the names of all the files under directory {\it dirname}
 113 to the array {\it files} (note that its old content is preserved). Only files
 114 matching the {\it filespec} are taken, with empty spec matching all the files.
 115
 116 The {\it flags} parameter should always include {\tt wxDIR\_FILES} or the array
 117 would be unchanged and should include {\tt wxDIR\_DIRS} flag to recurse into
 118 subdirectories (both flags are included in the value by default).
 119
 120 See also: \helpref{Traverse}{wxdirtraverse}
 121
 122
 123 \membersection{wxDir::FindFirst}\label{wxdirfindfirst}
 124
 125 \func{static wxString}{FindFirst}{\param{const wxString\& }{dirname}, \param{const wxString\& }{filespec}, \param{int }{flags = wxDIR\_DEFAULT}}
 126
 127 The function returns the path of the first file matching the given \arg{filespec}
 128 or an empty string if there are no files matching it.
 129
 130 The \arg{flags} parameter may or may not include {\tt wxDIR\_FILES}, the
 131 function always behaves as if it were specified. By default, \arg{flags}
 132 includes {\tt wxDIR\_DIRS} and so the function recurses into the subdirectories
 133 but if this flag is not specified, the function restricts the search only to
 134 the directory \arg{dirname} itself.
 135
 136 See also: \helpref{Traverse}{wxdirtraverse}
 137
 138
 139 \membersection{wxDir::GetFirst}\label{wxdirgetfirst}
 140
 141 \constfunc{bool}{GetFirst}{\param{wxString* }{filename}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
 142
 143 Start enumerating all files matching {\it filespec} (or all files if it is
 144 empty) and {\it flags}, return \true on success.
 145
 146
 147 \membersection{wxDir::GetName}\label{wxdirgetname}
 148
 149 \constfunc{wxString}{GetName}{\void}
 150
 151 Returns the name of the directory itself. The returned string does not have the
 152 trailing path separator (slash or backslash).
 153
 154
 155 \membersection{wxDir::GetNext}\label{wxdirgetnext}
 156
 157 \constfunc{bool}{GetNext}{\param{wxString* }{filename}}
 158
 159 Continue enumerating files which satisfy the criteria specified by the last
 160 call to \helpref{GetFirst}{wxdirgetfirst}.
 161
 162
 163 \membersection{wxDir::GetTotalSize}\label{wxdirgettotalsize}
 164
 165 \func{static wxULongLong}{GetTotalSize}{\param{const wxString\& }{dir}, \param{wxArrayString* }{filesSkipped = NULL}}
 166
 167 Returns the size (in bytes) of all files recursively found in {\tt dir} or
 168 {\tt wxInvalidSize} in case of error.
 169
 170 In case it happens that while traversing folders a file's size can not be read,
 171 that file is added to the {\tt filesSkipped} array, if not \NULL, and then
 172 skipped.
 173 This usually happens with some special folders which are locked by the operating system
 174 or by another process. Remember that when {\tt filesSkipped->GetCount()} is not zero,
 175 then the returned value is not 100\% accurate and, if the skipped files were big, it could be
 176 far from real size of the directory.
 177
 178 See also: \helpref{wxFileName::GetHumanReadableSize}{wxfilenamegethumanreadablesize},
 179 \helpref{wxGetDiskSpace}{wxgetdiskspace}
 180
 181
 182 \membersection{wxDir::HasFiles}\label{wxdirhasfiles}
 183
 184 \func{bool}{HasFiles}{\param{const wxString\& }{filespec = wxEmptyString}}
 185
 186 Returns {\tt true} if the directory contains any files matching the given
 187 {\it filespec}. If {\it filespec} is empty, look for any files at all. In any
 188 case, even hidden files are taken into account.
 189
 190
 191 \membersection{wxDir::HasSubDirs}\label{wxdirhassubdirs}
 192
 193 \func{bool}{HasSubDirs}{\param{const wxString\& }{dirspec = wxEmptyString}}
 194
 195 Returns {\tt true} if the directory contains any subdirectories (if a non
 196 empty {\it filespec} is given, only check for directories matching it).
 197 The hidden subdirectories are taken into account as well.
 198
 199
 200 \membersection{wxDir::IsOpened}\label{wxdirisopened}
 201
 202 \constfunc{bool}{IsOpened}{\void}
 203
 204 Returns true if the directory was successfully opened by a previous call to
 205 \helpref{Open}{wxdiropen}.
 206
 207
 208 \membersection{wxDir::Open}\label{wxdiropen}
 209
 210 \func{bool}{Open}{\param{const wxString\& }{dir}}
 211
 212 Open the directory for enumerating, returns {\tt true} on success
 213 or {\tt false} if an error occurred.
 214
 215
 216 \membersection{wxDir::Traverse}\label{wxdirtraverse}
 217
 218 \func{size\_t}{Traverse}{\param{wxDirTraverser\& }{sink}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
 219
 220 Enumerate all files and directories under the given directory recursively
 221 calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser}
 222 object for each of them.
 223
 224 More precisely, the function will really recurse into subdirectories if
 225 {\it flags} contains {\tt wxDIR\_DIRS} flag. It will ignore the files (but
 226 still possibly recurse into subdirectories) if {\tt wxDIR\_FILES} flag is
 227 given.
 228
 229 For each found directory, \helpref{sink.OnDir()}{wxdirtraverserondir} is called
 230 and \helpref{sink.OnFile()}{wxdirtraverseronfile} is called for every file.
 231 Depending on the return value, the enumeration may continue or stop.
 232
 233 The function returns the total number of files found or {\tt (size\_t)-1} on
 234 error.
 235
 236 See also: \helpref{GetAllFiles}{wxdirgetallfiles}
 237