clarified global and local config files behavior

[wxWidgets.git] / docs / latex / wx / dir.tex

diff --git a/docs/latex/wx/dir.tex b/docs/latex/wx/dir.tex
index 96144d5fa9fe7ac511d043107b06a028436b2af9..c9b6a29d5377a1b8d043c5fd7065fc32860c496b 100644 (file)
--- 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
 \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 
 
 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}
 
 
 \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}
 
 {\small
 \begin{verbatim}


@@ -74,12 +74,6 @@ enum
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \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}
 \membersection{wxDir::wxDir}\label{wxdirwxdir}
 
 \func{}{wxDir}{\void}


@@ -91,6 +85,7 @@ Default constructor, use \helpref{Open()}{wxdiropen} afterwards.
 Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened} 
 to test for errors.
 
 Opens the directory for enumeration, use \helpref{IsOpened()}{wxdirisopened} 
 to test for errors.
 

+

 \membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor}
 
 \func{}{\destruct{wxDir}}{\void}
 \membersection{wxDir::\destruct{wxDir}}\label{wxdirdtor}
 
 \func{}{\destruct{wxDir}}{\void}


@@ -98,50 +93,122 @@ to test for errors.
 Destructor cleans up the associated resources. It is not virtual and so this
 class is not meant to be used polymorphically.
 
 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
 
 \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::GetName}\label{wxdirgetname}
+
+\constfunc{wxString}{GetName}{\void}
+
+Returns the name of the directory itself. The returned string does not have the
+trailing path separator (slash or backslash).
+

 
 \membersection{wxDir::GetNext}\label{wxdirgetnext}
 
 \constfunc{bool}{GetNext}{\param{wxString* }{filename}}
 
 
 \membersection{wxDir::GetNext}\label{wxdirgetnext}
 
 \constfunc{bool}{GetNext}{\param{wxString* }{filename}}
 

-Continue enumerating files satisfying the criteria specified by the last call
-to \helpref{GetFirst}{wxdirgetfirst}.
+Continue enumerating files which satisfy the criteria specified by the last
+call to \helpref{GetFirst}{wxdirgetfirst}.
+
+
+\membersection{wxDir::GetTotalSize}\label{wxdirgettotalsize}
+
+\func{static wxULongLong}{GetTotalSize}{\param{const wxString\& }{dir}, \param{wxArrayString* }{filesSkipped = NULL}}
+
+Returns the size (in bytes) of all files recursively found in {\tt dir} or
+{\tt wxInvalidSize} in case of error.
+
+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.
+
+See also: \helpref{wxFileName::GetHumanReadableSize}{wxfilenamegethumanreadablesize},
+\helpref{wxGetDiskSpace}{wxgetdiskspace}
+

 
 \membersection{wxDir::HasFiles}\label{wxdirhasfiles}
 
 \func{bool}{HasFiles}{\param{const wxString\& }{filespec = wxEmptyString}}
 
 
 \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 
+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.
 
 {\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}}
 
 \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
+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.
 
 empty {\it filespec} is given, only check for directories matching it).
 The hidden subdirectories are taken into account as well.
 

+
+\membersection{wxDir::IsOpened}\label{wxdirisopened}
+
+\constfunc{bool}{IsOpened}{\void}
+
+Returns true if the directory was successfully opened by a previous call to 
+\helpref{Open}{wxdiropen}.
+
+
+\membersection{wxDir::Open}\label{wxdiropen}
+
+\func{bool}{Open}{\param{const wxString\& }{dir}}
+
+Open the directory for enumerating, returns {\tt true} on success
+or {\tt false} if an error occurred.
+
+

 \membersection{wxDir::Traverse}\label{wxdirtraverse}
 
 \func{size\_t}{Traverse}{\param{wxDirTraverser\& }{sink}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}
 \membersection{wxDir::Traverse}\label{wxdirtraverse}
 
 \func{size\_t}{Traverse}{\param{wxDirTraverser\& }{sink}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}


@@ -164,17 +231,3 @@ error.
 
 See also: \helpref{GetAllFiles}{wxdirgetallfiles}
 
 
 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}
-