X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4afd752902ae7c44f4b3dc2edb11d7c24f95ed54..a9249b2eb2a40d8c71f828669045c4ddaa8dc5ff:/docs/latex/wx/dir.tex?ds=sidebyside diff --git a/docs/latex/wx/dir.tex b/docs/latex/wx/dir.tex index 676d62c3b2..6a3dbe6a83 100644 --- a/docs/latex/wx/dir.tex +++ b/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} @@ -54,7 +63,7 @@ enum wxDIR_DOTDOT = 0x0008, // include '.' and '..' // by default, enumerate everything except '.' and '..' - wxDIR_DEFAULT = wxDIR\_FILES | wxDIR\_DIRS | wxDIR\_HIDDEN + wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN } \end{verbatim} } @@ -94,7 +103,7 @@ class is not meant to be used polymorphically. \func{bool}{Open}{\param{const wxString\& }{dir}} Open the directory for enumerating, returns TRUE on success or FALSE if an -error occured. +error occurred. \membersection{wxDir::IsOpened}\label{wxdirisopened} @@ -117,3 +126,134 @@ empty) and flags, return TRUE on success. Continue enumerating files satisfying the criteria specified by the last call to \helpref{GetFirst}{wxdirgetfirst}. +\membersection{wxDir::HasFiles}\label{wxdirhasfiles} + +\func{bool}{HasFiles}{\param{const wxString& }{filespec = wxEmptyString}} + +Returns {\tt TRUE} if the directory contains any files matching the given +{\it filespec}. If {\it filespec} is empty, look for any files at all. In any +case, even hidden files are taken into account. + +\membersection{wxDir::HasSubDirs}\label{wxdirhassubdirs} + +\func{bool}{HasSubDirs}{\param{const wxString& }{dirspec = wxEmptyString}} + +Returns {\tt TRUE} if the directory contains any subdirectories (if a non +empty {\it filespec} is given, only check for directories matching it). +The hidden subdirectories are taken into account as well. + +\membersection{wxDir::Traverse}\label{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{wxDir::GetAllFiles}\label{wxdirgetallfiles} + +\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} + + + +\latexignore{\rtfignore{\wxheading{Members}}} + +\membersection{wxDirTraverser::OnFile}\label{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}\label{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. +