X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d9ff0f91fbddae88286567cab74dcfb59c91fc0f..d9605e634b503651fd349a3d2c6781b2407ea273:/docs/latex/wx/dir.tex diff --git a/docs/latex/wx/dir.tex b/docs/latex/wx/dir.tex index 6a3dbe6a83..c9b6a29d53 100644 --- a/docs/latex/wx/dir.tex +++ b/docs/latex/wx/dir.tex @@ -12,8 +12,8 @@ \section{\class{wxDir}}\label{wxdir} 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. +allow enumerating of the files in a directory. wxDir allows to enumerate files +as well as directories. wxDir also provides a flexible way to enumerate files recursively using \helpref{Traverse}{wxdirtraverse} or a simpler @@ -50,8 +50,8 @@ No base class \wxheading{Constants} -These flags define what kind of filenames is included in the list of files -enumerated by GetFirst/GetNext +These flags define what kind of filename is included in the list of files +enumerated by GetFirst/GetNext. {\small \begin{verbatim} @@ -74,12 +74,6 @@ enum \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxDir::Exists}\label{wxdirexists} - -\func{static bool}{Exists}{\param{const wxString\& }{dir}} - -Test for existence of a directory with the given name - \membersection{wxDir::wxDir}\label{wxdirwxdir} \func{}{wxDir}{\void} @@ -91,169 +85,149 @@ Default constructor, use \helpref{Open()}{wxdiropen} afterwards. Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened} to test for errors. + \membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor} \func{}{\destruct{wxDir}}{\void} -Destructor cleans up the associated ressources. It is not virtual and so this +Destructor cleans up the associated resources. It is not virtual and so this class is not meant to be used polymorphically. -\membersection{wxDir::Open}\label{wxdiropen} -\func{bool}{Open}{\param{const wxString\& }{dir}} +\membersection{wxDir::Exists}\label{wxdirexists} -Open the directory for enumerating, returns TRUE on success or FALSE if an -error occurred. +\func{static bool}{Exists}{\param{const wxString\& }{dir}} -\membersection{wxDir::IsOpened}\label{wxdirisopened} +Test for existence of a directory with the given name -\constfunc{bool}{IsOpened}{\void} -Returns TRUE if the directory was successfully opened by a previous call to -\helpref{Open}{wxdiropen}. +\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 content 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} + + +\membersection{wxDir::FindFirst}\label{wxdirfindfirst} + +\func{static wxString}{FindFirst}{\param{const wxString\& }{dirname}, \param{const wxString\& }{filespec}, \param{int }{flags = wxDIR\_DEFAULT}} + +The function returns the path of the first file matching the given \arg{filespec} +or an empty string if there are no files matching it. + +The \arg{flags} parameter may or may not include {\tt wxDIR\_FILES}, the +function always behaves as if it were specified. By default, \arg{flags} +includes {\tt wxDIR\_DIRS} and so the function recurses into the subdirectories +but if this flag is not specified, the function restricts the search only to +the directory \arg{dirname} itself. + +See also: \helpref{Traverse}{wxdirtraverse} + \membersection{wxDir::GetFirst}\label{wxdirgetfirst} \constfunc{bool}{GetFirst}{\param{wxString* }{filename}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}} Start enumerating all files matching {\it filespec} (or all files if it is -empty) and flags, return TRUE on success. +empty) and {\it flags}, return \true on success. -\membersection{wxDir::GetNext}\label{wxdirgetnext} -\constfunc{bool}{GetNext}{\param{wxString* }{filename}} +\membersection{wxDir::GetName}\label{wxdirgetname} -Continue enumerating files satisfying the criteria specified by the last call -to \helpref{GetFirst}{wxdirgetfirst}. +\constfunc{wxString}{GetName}{\void} -\membersection{wxDir::HasFiles}\label{wxdirhasfiles} +Returns the name of the directory itself. The returned string does not have the +trailing path separator (slash or backslash). -\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::GetNext}\label{wxdirgetnext} -\membersection{wxDir::HasSubDirs}\label{wxdirhassubdirs} +\constfunc{bool}{GetNext}{\param{wxString* }{filename}} -\func{bool}{HasSubDirs}{\param{const wxString& }{dirspec = wxEmptyString}} +Continue enumerating files which satisfy the criteria specified by the last +call to \helpref{GetFirst}{wxdirgetfirst}. -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} +\membersection{wxDir::GetTotalSize}\label{wxdirgettotalsize} -\func{size\_t}{Traverse}{\param{wxDirTraverser& }{sink}, \param{const wxString& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}} +\func{static wxULongLong}{GetTotalSize}{\param{const wxString\& }{dir}, \param{wxArrayString* }{filesSkipped = NULL}} -Enumerate all files and directories under the given directory recursively -calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser} -object for each of them. +Returns the size (in bytes) of all files recursively found in {\tt dir} or +{\tt wxInvalidSize} in case of error. -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. +In case it happens that while traversing folders a file's size can not be read, +that file is added to the {\tt filesSkipped} array, if not \NULL, and then +skipped. +This usually happens with some special folders which are locked by the operating system +or by another process. Remember that when {\tt filesSkipped->GetCount()} is not zero, +then the returned value is not 100\% accurate and, if the skipped files were big, it could be +far from real size of the directory. -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. +See also: \helpref{wxFileName::GetHumanReadableSize}{wxfilenamegethumanreadablesize}, +\helpref{wxGetDiskSpace}{wxgetdiskspace} -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} +\membersection{wxDir::HasFiles}\label{wxdirhasfiles} -\func{static size\_t}{GetAllFiles}{\param{const wxString& }{dirname}, \param{wxArrayString *}{files}, \param{const wxString& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}} +\func{bool}{HasFiles}{\param{const wxString\& }{filespec = wxEmptyString}} -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. +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. -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} +\membersection{wxDir::HasSubDirs}\label{wxdirhassubdirs} -\section{\class{wxDirTraverser}}\label{wxdirtraverser} +\func{bool}{HasSubDirs}{\param{const wxString\& }{dirspec = wxEmptyString}} -wxDirTraverser is an abstract interface which must be implemented by objects -passed to \helpref{Traverse}{wxdirtraverse} function. +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. -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} +\membersection{wxDir::IsOpened}\label{wxdirisopened} -\wxheading{Derived from} +\constfunc{bool}{IsOpened}{\void} -No base class +Returns true if the directory was successfully opened by a previous call to +\helpref{Open}{wxdiropen}. -\wxheading{Constants} -The elements of {\tt wxDirTraverseResult} are the possible return values of the -callback functions: +\membersection{wxDir::Open}\label{wxdiropen} -{\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} -} +\func{bool}{Open}{\param{const wxString\& }{dir}} -\wxheading{Include files} +Open the directory for enumerating, returns {\tt true} on success +or {\tt false} if an error occurred. - -\latexignore{\rtfignore{\wxheading{Members}}} +\membersection{wxDir::Traverse}\label{wxdirtraverse} -\membersection{wxDirTraverser::OnFile}\label{wxdirtraverseronfile} +\func{size\_t}{Traverse}{\param{wxDirTraverser\& }{sink}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}} -\func{virtual wxDirTraverseResult}{OnFile}{\param{const wxString& }{filename}} +Enumerate all files and directories under the given directory recursively +calling the element of the provided \helpref{wxDirTraverser}{wxdirtraverser} +object for each of them. -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. +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. -\membersection{wxDirTraverser::OnDir}\label{wxdirtraverserondir} +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. -\func{virtual wxDirTraverseResult}{OnDir}{\param{const wxString& }{dirname}} +The function returns the total number of files found or {\tt (size\_t)-1} on +error. -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. +See also: \helpref{GetAllFiles}{wxdirgetallfiles}