added wxDir::Traverse

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@10226 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/dir.tex

@@ -1,8 +1,13 @@
-%
-% automatically generated by HelpGen from
-% include\wx\dir.h at 11/Dec/99 00:55:30
-%
-
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        dir.tex
+%% Purpose:     wxDir documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     04.04.00
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Vadim Zeitlin
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxDir}}\label{wxdir}
 
@@ -10,6 +15,10 @@ wxDir is a portable equivalent of Unix {open/read/close}dir functions which
 allow enumerating of the files in a directory. wxDir allows enumerate files as
 well as directories.
 
+wxDir also provides a flexible way to enumerate files recursively using 
+\helpref{Traverse}{wxdirtraverse} or a simpler 
+\helpref{GetAllFiles}{wxdirgetallfiles} function.
+
 Example of use:
 
 \begin{verbatim}
@@ -117,3 +126,117 @@ empty) and flags, return TRUE on success.
 Continue enumerating files satisfying the criteria specified by the last call
 to \helpref{GetFirst}{wxdirgetfirst}.
 
+\membersection{wxDir::Traverse}{wxdirtraverse}
+
+\func{size\_t}{Traverse}{\param{wxDirTraverser& }{sink}, \param{const wxString& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
+
+Enumerate all files and directories under the given directory recursively
+calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser} 
+object for each of them.
+
+More precisely, the function will really recurse into subdirectories if 
+{\it flags} contains {\tt wxDIR\_DIRS} flag. It will ignore the files (but
+still possibly recurse into subdirectories) if {\tt wxDIR\_FILES} flag is
+given.
+
+For each found directory, \helpref{sink.OnDir()}{wxdirtraverserondir} is called
+and \helpref{sink.OnFile()}{wxdirtraverseronfile} is called for every file.
+Depending on the return value, the enumeration may continue or stop.
+
+The function returns the total number of files found or {\tt (size\_t)-1} on
+error.
+
+See also: \helpref{GetAllFiles}{wxdirgetallfiles}
+
+\membersection{wxDirTraverser::GetAllFiles}{wxdirtraversergetallfiles}
+
+\func{static size\_t}{GetAllFiles}{\param{const wxString& }{dirname}, \param{wxArrayString *}{files}, \param{const wxString& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
+
+The function appends the names of all the files under directory {\it dirname} 
+to the array {\it files} (note that its old contents is preserved). Only files
+matching the {\it filespec} are taken, with empty spec matching all the files.
+
+The {\it flags} parameter should always include {\tt wxDIR\_FILES} or the array
+would be unchanged and should include {\tt wxDIR\_DIRS} flag to recurse into
+subdirectories (both flags are included in the value by default).
+
+See also: \helpref{Traverse}{wxdirtraverse}
+
+\section{\class{wxDirTraverser}}\label{wxdirtraverser}
+
+wxDirTraverser is an abstract interface which must be implemented by objects
+passed to \helpref{Traverse}{wxdirtraverse} function.
+
+Example of use (this works almost like \helpref{GetAllFiles}{wxdirgetallfiles}):
+
+\begin{verbatim}
+    class wxDirTraverserSimple : public wxDirTraverser
+    {
+    public:
+        wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
+
+        virtual wxDirTraverseResult OnFile(const wxString& filename)
+        {
+            m_files.Add(filename);
+            return wxDIR_CONTINUE;
+        }
+
+        virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
+        {
+            return wxDIR_CONTINUE;
+        }
+
+    private:
+        wxArrayString& m_files;
+    };
+
+    // get the names of all files in the array
+    wxArrayString files;
+    wxDirTraverserSimple traverser(files);
+
+    wxDir dir(dirname);
+    dir.Traverse(traverser);
+\end{verbatim}
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Constants}
+
+The elements of {\tt wxDirTraverseResult} are the possible return values of the
+callback functions:
+
+{\small
+\begin{verbatim}
+enum wxDirTraverseResult
+{
+    wxDIR_IGNORE = -1,      // ignore this directory but continue with others
+    wxDIR_STOP,             // stop traversing
+    wxDIR_CONTINUE          // continue into this directory
+};
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/dir.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDirTraverser::OnFile}{wxdirtraverseronfile}
+
+\func{virtual wxDirTraverseResult}{OnFile}{\param{const wxString& }{filename}}
+
+This function is called for each file. It may return {\tt wxDIR\_STOP} to abort
+traversing (for example, if the file being searched is found) or 
+{\tt wxDIR\_CONTINUE} to proceed.
+
+\membersection{wxDirTraverser::OnDir}{wxdirtraverserondir}
+
+\func{virtual wxDirTraverseResult}{OnDir}{\param{const wxString& }{dirname}}
+
+This function is called for each directory. It may return {\tt wxSIR\_STOP} 
+to abort traversing completely, {\tt wxDIR\_IGNORE} to skip this directory but
+continue with others or {\tt wxDIR\_CONTINUE} to enumerate all files and
+subdirectories in this directory.
+