allow to optionally use vendor name component in standard paths (slightly modified...

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

diff --git a/docs/latex/wx/filename.tex b/docs/latex/wx/filename.tex
index 16dc6935b213a5ca132d3ffabbfd2720babf417a..9efca1ad593053b7029daed5ed18f14f508682ff 100644 (file)
--- a/docs/latex/wx/filename.tex
+++ b/docs/latex/wx/filename.tex
@@ -19,6 +19,47 @@ Second, it includes the functions for working with the files itself. Note that
 to change the file data you should use \helpref{wxFile}{wxfile} class instead.
 wxFileName provides functions for working with the file attributes.
 
 to change the file data you should use \helpref{wxFile}{wxfile} class instead.
 wxFileName provides functions for working with the file attributes.
 

+When working with directory names (i.e. without filename and extension)
+make sure not to misuse the file name part of this class with the last
+directory. Instead initialize the wxFileName instance like this:
+
+\begin{verbatim}
+wxFileName dirname( wxT("C:\mydir"), wxEmptyString );
+MyMethod( dirname.GetPath() );
+\end{verbatim}
+
+The same can be done using the static method \helpref{wxFileName::DirName}{wxfilenamedirname}:
+
+\begin{verbatim}
+wxFileName dirname = wxFileName::DirName( wxT("C:\mydir") );
+MyMethod( dirname.GetPath() );
+\end{verbatim}
+
+Accordingly, methods dealing with directories or directory names
+like \helpref{IsDirReadable}{wxfilenameisdirreadable} use
+\helpref{GetPath}{wxfilenamegetpath} whereas methods dealing 
+with file names like \helpref{IsFileReadable}{wxfilenameisfilereadable}
+use \helpref{GetFullPath}{wxfilenamegetfullpath}.
+
+If it is not known wether a string contains a directory name or
+a complete file name (such as when interpreting user input) you need to use
+the static function \helpref{wxFileName::DirExists}{wxfilenamedirexists}
+(or its identical variants \helpref{wxDir::Exists}{wxdirexists} and
+\helpref{wxDirExists}{functionwxdirexists}) and construct the wxFileName
+instance accordingly. This will only work if the directory actually exists,
+of course:
+
+\begin{verbatim}
+wxString user_input;
+// get input from user
+
+wxFileName fname;
+if (wxDirExists(user_input))
+    fname.AssignDir( user_input );
+else
+    fname.Assign( user_input );
+\end{verbatim}
+

 \wxheading{Derived from}
 
 No base class
 \wxheading{Derived from}
 
 No base class


@@ -27,6 +68,10 @@ No base class
 
 <wx/filename.h>
 
 
 <wx/filename.h>
 

+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+

 \wxheading{Data structures}
 
 Many wxFileName methods accept the path format argument which is by\rtfsp
 \wxheading{Data structures}
 
 Many wxFileName methods accept the path format argument which is by\rtfsp


@@ -93,7 +138,17 @@ class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp
 
 \membersection{File name construction}\label{filenameconstruction}
 
 
 \membersection{File name construction}\label{filenameconstruction}
 

-TODO.
+You can initialize a wxFileName instance using one of the following functions:
+
+\helpref{wxFileName constructors}{wxfilenamewxfilename}\\
+\helpref{Assign}{wxfilenameassign}\\
+\helpref{AssignCwd}{wxfilenameassigncwd}\\
+\helpref{AssignDir}{wxfilenameassigndir}\\
+\helpref{AssignHomeDir}{wxfilenameassignhomedir}\\
+\helpref{AssignHomeTempFileName}{wxfilenameassigntempfilename}\\
+\helpref{DirName}{wxfilenamedirname}\\
+\helpref{FileName}{wxfilenamefilename}\\
+\helpref{operator $=$}{wxfilenameoperatorassign}

 
 
 \membersection{File tests}\label{filetests}
 
 
 \membersection{File tests}\label{filetests}


@@ -105,7 +160,15 @@ with such name exists and \helpref{DirExists}{wxfilenamedirexists} can be used
 to test for directory existence.
 
 File names should be compared using \helpref{SameAs}{wxfilenamesameas} method
 to test for directory existence.
 
 File names should be compared using \helpref{SameAs}{wxfilenamesameas} method

-or \helpref{$==$}{wxfilenameoperatorequal}.
+or \helpref{operator $==$}{wxfilenameoperatorequal}.
+
+For testing basic access modes, you can use:
+
+\helpref{IsDirWritable}{wxfilenameisdirwritable}\\
+\helpref{IsDirReadable}{wxfilenameisdirreadable}\\
+\helpref{IsFileWritable}{wxfilenameisfilewritable}\\
+\helpref{IsFileReadable}{wxfilenameisfilereadable}\\
+\helpref{IsFileExecutable}{wxfilenameisfileexecutable}

 
 
 \membersection{File name components}\label{filenamecomponents}
 
 
 \membersection{File name components}\label{filenamecomponents}


@@ -513,6 +576,40 @@ This is the same as calling \helpref{GetPath}{wxfilenamegetpath}
 Return the short form of the path (returns identity on non-Windows platforms).
 
 
 Return the short form of the path (returns identity on non-Windows platforms).
 
 

+\membersection{wxFileName::GetSize}\label{wxfilenamegetsize}
+
+\constfunc{wxULongLong}{GetSize}{\void}
+
+\func{static wxULongLong}{GetSize}{\param{const wxString\& }{filename}}
+
+Returns the size of this file (first form) or the size of the given file (second form).
+If the file does not exist or its size could not be read (because e.g. the file is locked
+by another process) the returned value is {\tt wxInvalidSize}.
+
+
+\membersection{wxFileName::GetHumanReadableSize}\label{wxfilenamegethumanreadablesize}
+
+\constfunc{wxString}{GetHumanReadableSize}{\param{const wxString\& }{failmsg = "Not available"}, \param{int }{precision = 1}}
+
+\func{static wxString}{GetHumanReadableSize}{\param{const wxULongLong\& }{bytes}, \param{const wxString\& }{nullsize = "Not available"}, \param{int }{precision = 1}}
+
+Returns the size of this file (first form) or the given number of bytes (second form)
+in a human-readable form.
+
+If the size could not be retrieved the {\tt failmsg} string is returned (first form).
+If {\tt bytes} is {\tt wxInvalidSize} or zero, then {\tt nullsize} is returned (second form).
+
+In case of success, the returned string is a floating-point number with {\tt precision} decimal digits
+followed by the size unit (B, kB, MB, GB, TB: respectively bytes, kilobytes, megabytes, gigabytes, terabytes).
+
+
+\membersection{wxFileName::GetTempDir}\label{wxfilenamegettempdir}
+
+\func{static wxString}{GetTempDir}{\void}
+
+Returns the directory used for temporary files.
+
+

 \membersection{wxFileName::GetTimes}\label{wxfilenamegettimes}
 
 \constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}
 \membersection{wxFileName::GetTimes}\label{wxfilenamegettimes}
 
 \constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}


@@ -525,6 +622,12 @@ under Windows and the inode change time under Unix (as it is impossible to
 retrieve the real file creation time there anyhow) which can also be changed
 by many operations after the file creation.
 
 retrieve the real file creation time there anyhow) which can also be changed
 by many operations after the file creation.
 

+If no filename or extension is specified in this instance of wxFileName
+(and therefore \helpref{IsDir}{wxfilenameisdir} returns {\tt true}) then
+this function will return the directory times of the path specified by
+\helpref{GetPath}{wxfilenamegetpath}, otherwise the file times of the
+file specified by \helpref{GetFullPath}{wxfilenamegetfullpath}.
+

 Any of the pointers may be {\tt NULL} if the corresponding time is not
 needed.
 
 Any of the pointers may be {\tt NULL} if the corresponding time is not
 needed.
 


@@ -592,6 +695,56 @@ Returns {\tt true} if this filename is absolute.
 Returns {\tt true} if the file names of this type are case-sensitive.
 
 
 Returns {\tt true} if the file names of this type are case-sensitive.
 
 

+\membersection{wxFileName::IsDirReadable}\label{wxfilenameisdirreadable}
+
+\constfunc{bool}{IsDirReadable}{\void}
+
+\func{static bool}{IsDirReadable}{\param{const wxString\& }{dir}}
+
+Returns {\tt true} if the directory component of this instance (or given \arg{dir})
+is an existing directory and this process has read permissions on it.
+Read permissions on a directory mean that you can list the directory contents but it
+doesn't imply that you have read permissions on the files contained.
+
+
+\membersection{wxFileName::IsDirWritable}\label{wxfilenameisdirwritable}
+
+\constfunc{bool}{IsDirWritable}{\void}
+
+\func{static bool}{IsDirWritable}{\param{const wxString\& }{dir}}
+
+Returns {\tt true} if the directory component of this instance (or given \arg{dir})
+is an existing directory and this process has write permissions on it.
+Write permissions on a directory mean that you can create new files in the directory.
+
+
+\membersection{wxFileName::IsFileExecutable}\label{wxfilenameisfileexecutable}
+
+\constfunc{bool}{IsFileExecutable}{\void}
+
+\func{static bool}{IsFileExecutable}{\param{const wxString\& }{file}}
+
+Returns {\tt true} if a file with this name exists and if this process has execute permissions on it.
+
+
+\membersection{wxFileName::IsFileReadable}\label{wxfilenameisfilereadable}
+
+\constfunc{bool}{IsFileReadable}{\void}
+
+\func{static bool}{IsFileReadable}{\param{const wxString\& }{file}}
+
+Returns {\tt true} if a file with this name exists and if this process has read permissions on it.
+
+
+\membersection{wxFileName::IsFileWritable}\label{wxfilenameisfilewritable}
+
+\constfunc{bool}{IsFileWritable}{\void}
+
+\func{static bool}{IsFileWritable}{\param{const wxString\& }{file}}
+
+Returns {\tt true} if a file with this name exists and if this process has write permissions on it.
+
+

 \membersection{wxFileName::IsOk}\label{wxfilenameisok}
 
 \constfunc{bool}{IsOk}{\void}
 \membersection{wxFileName::IsOk}\label{wxfilenameisok}
 
 \constfunc{bool}{IsOk}{\void}


@@ -715,20 +868,25 @@ any or-combination of the following constants:
 
 \begin{twocollist}
 \twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values}
 
 \begin{twocollist}
 \twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values}

-\twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . and prepend cwd}
-\twocolitem{{\bf wxPATH\_NORM\_TILDE}}{Unix only: replace ~ and ~user}
+\twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . when possible; if there are too many .. and thus they cannot be all removed, \false will be returned}

 \twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to lower case}
 \twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to lower case}

-\twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute}
+\twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute prepending \arg{cwd}}

 \twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form}
 \twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)}
 \twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form}
 \twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)}

+\twocolitem{{\bf wxPATH\_NORM\_TILDE}}{replace ~ and ~user (Unix only)}

 \twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}}
 \end{twocollist}
 }%
 
 \docparam{cwd}{If not empty, this directory will be used instead of current
 \twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}}
 \end{twocollist}
 }%
 
 \docparam{cwd}{If not empty, this directory will be used instead of current

-working directory in normalization.}
+working directory in normalization (see wxPATH\_NORM\_ABSOLUTE).}
+
+\docparam{format}{The file name format to use when processing the paths, native by default.}
+
+
+\wxheading{Return value}

 
 

-\docparam{format}{The file name format, native by default.}
+\true if normalization was successfully or \false otherwise.

 
 
 \membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}
 
 
 \membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}