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 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