X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2569938d392eace21ae617355f9c1a636185f36f..e536d73ac4427ba43f0ae70c7f9369420eff1524:/docs/latex/wx/filename.tex

diff --git a/docs/latex/wx/filename.tex b/docs/latex/wx/filename.tex
index 992aead482..0c0d22dc1e 100644
--- a/docs/latex/wx/filename.tex
+++ b/docs/latex/wx/filename.tex
@@ -14,15 +14,19 @@
 wxFileName encapsulates a file name. This class serves two purposes: first, it
 provides the functions to split the file names into components and to recombine
 these components in the full file name which can then be passed to the OS file
-functions (and \helpref{wxWindows functions}{filefunctions} wrapping them).
+functions (and \helpref{wxWidgets functions}{filefunctions} wrapping them).
 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,
+to change the file data you should use \helpref{wxFile}{wxfile} class instead.
 wxFileName provides functions for working with the file attributes.
 
 \wxheading{Derived from}
 
 No base class
 
+\wxheading{Include files}
+
+<wx/filename.h>
+
 \wxheading{Data structures}
 
 Many wxFileName methods accept the path format argument which is by\rtfsp
@@ -38,215 +42,373 @@ enum wxPathFormat
 {
     wxPATH_NATIVE = 0,      // the path format for the current platform
     wxPATH_UNIX,
+    wxPATH_BEOS = wxPATH_UNIX,
     wxPATH_MAC,
     wxPATH_DOS,
+    wxPATH_WIN = wxPATH_DOS,
+    wxPATH_OS2 = wxPATH_DOS,
     wxPATH_VMS,
 
-    wxPATH_BEOS = wxPATH_UNIX,
-    wxPATH_WIN = wxPATH_DOS,
-    wxPATH_OS2 = wxPATH_DOS
+    wxPATH_MAX // Not a valid value for specifying path format
 }
 \end{verbatim}
 
-The kind of normalization to do with the file name: these values can be
-or'd together to perform several operations at once in\rtfsp
-\helpref{Normalize}{wxfilenamenormalize}.
+\latexignore{\rtfignore{\wxheading{Function groups}}}
 
-\begin{verbatim}
-enum wxPathNormalize
-{
-    wxPATH_NORM_ENV_VARS = 0x0001,  // replace env vars with their values
-    wxPATH_NORM_DOTS     = 0x0002,  // squeeze all .. and . and prepend cwd
-    wxPATH_NORM_TILDE    = 0x0004,  // Unix only: replace ~ and ~user
-    wxPATH_NORM_CASE     = 0x0008,  // if case insensitive => tolower
-    wxPATH_NORM_ABSOLUTE = 0x0010,  // make the path absolute
-    wxPATH_NORM_LONG =     0x0020,  // make the path the long form
-    wxPATH_NORM_ALL      = 0x003f
-}
-\end{verbatim}
+
+\membersection{File name format}\label{filenameformat}
+
+wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
+and VMS formats. Although these formats are quite different, wxFileName tries
+to treat them all in the same generic way. It supposes that all file names
+consist of the following parts: the volume (also known as drive under Windows
+or device under VMS), the path which is a sequence of directory names separated
+by the \helpref{path separators}{wxfilenamegetpathseparators} and the full
+filename itself which, in turn, is composed from the base file name and the
+extension. All of the individual components of the file name may be empty and,
+for example, the volume name is always empty under Unix, but if they are all
+empty simultaneously, the filename object is considered to be in an invalid
+state and \helpref{IsOk}{wxfilenameisok} returns {\tt false} for it.
+
+File names can be case-sensitive or not, the function\rtfsp
+\helpref{IsCaseSensitive}{wxfilenameiscasesensitive} allows to determine this.
+
+The rules for determining if the file name is absolute or relative also depends
+on the file name format and the only portable way to answer to this question is
+to use \helpref{IsAbsolute}{wxfilenameisabsolute} method. To ensure that the
+filename is absolute you may use \helpref{MakeAbsolute}{wxfilenamemakeabsolute}.
+There is also an inverse function 
+\helpref{MakeRelativeTo}{wxfilenamemakerelativeto} which undoes what
+\helpref{Normalize(wxPATH\_NORM\_DOTS)}{wxfilenamenormalize} does.
+
+Other functions returning information about the file format provided by this
+class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp
+\helpref{IsPathSeparator}{wxfilenameispathseparator}.
+
+\helpref{IsRelative}{wxfilenameisrelative}
+
+
+\membersection{File name construction}\label{filenameconstruction}
+
+TODO.
+
+
+\membersection{File tests}\label{filetests}
+
+Before doing the other tests you should use \helpref{IsOk}{wxfilenameisok} to
+verify that the filename is well defined. If it is, 
+\helpref{FileExists}{wxfilenamefileexists} can be used to test if a file with
+such name exists and \helpref{DirExists}{wxfilenamedirexists} - if a directory
+with this name exists.
+
+File names should be compared using \helpref{SameAs}{wxfilenamesameas} method
+or \helpref{$==$}{wxfilenameoperatorequal}.
+
+
+\membersection{File name components}\label{filenamecomponents}
+
+These functions allow to examine and modify the individual directories of the
+path:
+
+\helpref{AppendDir}{wxfilenameappenddir}\\
+\helpref{InsertDir}{wxfilenameinsertdir}\\
+\helpref{GetDirCount}{wxfilenamegetdircount}
+\helpref{PrependDir}{wxfilenameprependdir}\\
+\helpref{RemoveDir}{wxfilenameremovedir}\\
+\helpref{RemoveLastDir}{wxfilenameremovelastdir}
+
+To change the components of the file name individually you can use the
+following functions:
+
+\helpref{GetExt}{wxfilenamegetext}\\
+\helpref{GetName}{wxfilenamegetname}\\
+\helpref{GetVolume}{wxfilenamegetvolume}\\
+\helpref{HasExt}{wxfilenamehasext}\\
+\helpref{HasName}{wxfilenamehasname}\\
+\helpref{HasVolume}{wxfilenamehasvolume}\\
+\helpref{SetExt}{wxfilenamesetext}\\
+\helpref{ClearExt}{wxfilenameclearext}\\
+\helpref{SetEmptyExt}{wxfilenamesetemptyext}\\
+\helpref{SetName}{wxfilenamesetname}\\
+\helpref{SetVolume}{wxfilenamesetvolume}\\
+
+
+\membersection{Operations}\label{filenameoperations}
+
+These methods allow to work with the file creation, access and modification
+times. Note that not all filesystems under all platforms implement these times
+in the same way. For example, the access time under Windows has a resolution of
+one day (so it is really the access date and not time). The access time may be
+updated when the file is executed or not depending on the platform.
+
+\helpref{GetModificationTime}{wxfilenamegetmodificationtime}\\
+\helpref{GetTimes}{wxfilenamegettimes}\\
+\helpref{SetTimes}{wxfilenamesettimes}\\
+\helpref{Touch}{wxfilenametouch}
+
+Other file system operations functions are:
+
+\helpref{Mkdir}{wxfilenamemkdir}\\
+\helpref{Rmdir}{wxfilenamermdir}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilenamedef}
+
+\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename}
 
 \func{}{wxFileName}{\void}
 
 Default constructor.
 
-\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilenamecopy}
-
 \func{}{wxFileName}{\param{const wxFileName\& }{filename}}
 
 Copy constructor.
 
-\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename1}
-
 \func{}{wxFileName}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-from a full filename: if it terminates with a '/', a directory path
-is contructed (the name will be empty), otherwise a file name and
-extension are extracted from it
-
-
-\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename2}
+Constructor taking a full filename. If it terminates with a '/', a directory path
+is constructed (the name will be empty), otherwise a file name and
+extension are extracted from it.
 
 \func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-from a directory name and a file name
+Constructor from a directory name and a file name.
 
+\func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename3}
+Constructor from a directory name, base file name and extension.
 
-\func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{}{wxFileName}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-from a directory name, file base name and extension
+Constructor from a volume name, a directory name, base file name and extension.
 
 
 \membersection{wxFileName::AppendDir}\label{wxfilenameappenddir}
 
 \func{void}{AppendDir}{\param{const wxString\& }{dir}}
 
+Appends a directory component to the path. This component should contain a
+single directory name level, i.e. not contain any path or volume separators nor
+should it be empty, otherwise the function does nothing (and generates an
+assert failure in debug build).
+
 
 \membersection{wxFileName::Assign}\label{wxfilenameassign}
 
 \func{void}{Assign}{\param{const wxFileName\& }{filepath}}
 
-
-\membersection{wxFileName::Assign}\label{wxfilenameassign}
-
 \func{void}{Assign}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-
-\membersection{wxFileName::Assign}\label{wxfilenameassign}
+\func{void}{Assign}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{bool }{hasExt}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
 \func{void}{Assign}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-
-\membersection{wxFileName::Assign}\label{wxfilenameassign}
-
 \func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-
-\membersection{wxFileName::Assign}\label{wxfilenameassign}
-
 \func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
+Creates the file name from various combinations of data.
+
 
 \membersection{wxFileName::AssignCwd}\label{wxfilenameassigncwd}
 
-\func{void}{AssignCwd}{\void}
+\func{static void}{AssignCwd}{\param{const wxString\& }{volume = wxEmptyString}}
 
-various file/dir operations
-retrieve the value of the current working directory
+Makes this object refer to the current working directory on the specified
+volume (or current volume if {\it volume} is empty).
+
+\wxheading{See also}
+
+\helpref{GetCwd}{wxfilenamegetcwd}
 
 
 \membersection{wxFileName::AssignDir}\label{wxfilenameassigndir}
 
 \func{void}{AssignDir}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-empty volume
+Sets this file name object to the given directory name. The name and extension
+will be empty.
 
 
 \membersection{wxFileName::AssignHomeDir}\label{wxfilenameassignhomedir}
 
 \func{void}{AssignHomeDir}{\void}
 
-get the value of user home (Unix only mainly)
+Sets this file name object to the home directory.
 
 
 \membersection{wxFileName::AssignTempFileName}\label{wxfilenameassigntempfilename}
 
-\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}}
+\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}}
 
-get a temp file name starting with thespecified prefix
+The function calls \helpref{CreateTempFileName}{wxfilenamecreatetempfilename} to
+create a temporary file and sets this object to the name of the file. If a
+temporary file couldn't be created, the object is put into the\rtfsp
+\helpref{invalid}{wxfilenameisok} state.
 
 
 \membersection{wxFileName::Clear}\label{wxfilenameclear}
 
 \func{void}{Clear}{\void}
 
-reset all components to default, uninitialized state
+Reset all components to default, uninitialized state.
 
 
-\membersection{wxFileName::DirExists}\label{wxfilenamedirexists}
+\membersection{wxFileName::ClearExt}\label{wxfilenameclearext}
+
+\func{void}{SetClearExt}{\void}
+
+Removes the extension from the file name resulting in a 
+file name with no trailing dot.
+
+\wxheading{See also}
+
+\helpref{SetExt}{wxfilenamesetext}
+\helpref{SetEmptyExt}{wxfilenamesetemptyext}
+
+\membersection{wxFileName::CreateTempFileName}\label{wxfilenamecreatetempfilename}
+
+\func{static wxString}{CreateTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}}
+
+Returns a temporary file name starting with the given {\it prefix}. If
+the {\it prefix} is an absolute path, the temporary file is created in this
+directory, otherwise it is created in the default system directory for the
+temporary files or in the current directory.
+
+If the function succeeds, the temporary file is actually created. If\rtfsp
+{\it fileTemp} is not {\tt NULL}, this file will be opened using the name of
+the temporary file. When possible, this is done in an atomic way ensuring that
+no race condition occurs between the temporary file name generation and opening
+it which could often lead to security compromise on the multiuser systems.
+If {\it fileTemp} is {\tt NULL}, the file is only created, but not opened.
+
+Under Unix, the temporary file will have read and write permissions for the
+owner only to minimize the security problems.
+
+\wxheading{Parameters}
+
+\docparam{prefix}{Prefix to use for the temporary file name construction}
 
-\func{bool}{DirExists}{\void}
+\docparam{fileTemp}{The file to open or {\tt NULL} to just get the name}
 
-does the directory with this name exists?
+\wxheading{Return value}
+
+The full temporary file name or an empty string on error.
 
 
 \membersection{wxFileName::DirExists}\label{wxfilenamedirexists}
 
-\func{bool}{DirExists}{\param{const wxString\& }{dir}}
+\constfunc{bool}{DirExists}{\void}
+
+\func{static bool}{DirExists}{\param{const wxString\& }{dir}}
+
+Returns {\tt true} if the directory with this name exists.
 
 
 \membersection{wxFileName::DirName}\label{wxfilenamedirname}
 
-\func{wxFileName}{DirName}{\param{const wxString\& }{dir}}
+\func{static wxFileName}{DirName}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the object corresponding to the directory with the given name.
+The {\it dir} parameter may have trailing path separator or not.
+
 
 
 \membersection{wxFileName::FileExists}\label{wxfilenamefileexists}
 
-\func{bool}{FileExists}{\void}
+\constfunc{bool}{FileExists}{\void}
 
-does the file with this name exists?
+\func{static bool}{FileExists}{\param{const wxString\& }{file}}
 
+Returns {\tt true} if the file with this name exists.
 
-\membersection{wxFileName::FileExists}\label{wxfilenamefileexists}
+\wxheading{See also}
+
+\helpref{DirExists}{wxfilenamedirexists}
 
-\func{bool}{FileExists}{\param{const wxString\& }{file}}
 
 
 \membersection{wxFileName::FileName}\label{wxfilenamefilename}
 
-\func{wxFileName}{FileName}{\param{const wxString\& }{file}}
+\func{static wxFileName}{FileName}{\param{const wxString\& }{file}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the file name object corresponding to the given {\it file}. This
+function exists mainly for symmetry with \helpref{DirName}{wxfilenamedirname}.
 
-static pseudo constructors
 
 
 \membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd}
 
-\func{wxString}{GetCwd}{\void}
+\func{static wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}
+
+Retrieves the value of the current working directory on the specified volume. If
+the volume is empty, the program's current working directory is returned for the
+current volume.
+
+\wxheading{Return value}
+
+The string containing the current working directory or an empty string on
+error.
+
+\wxheading{See also}
+
+\helpref{AssignCwd}{wxfilenameassigncwd}
 
 
 \membersection{wxFileName::GetDirCount}\label{wxfilenamegetdircount}
 
 \constfunc{size\_t}{GetDirCount}{\void}
 
+Returns the number of directories in the file name.
+
 
 \membersection{wxFileName::GetDirs}\label{wxfilenamegetdirs}
 
 \constfunc{const wxArrayString\&}{GetDirs}{\void}
 
+Returns the directories in string array form.
+
 
 \membersection{wxFileName::GetExt}\label{wxfilenamegetext}
 
 \constfunc{wxString}{GetExt}{\void}
 
+Returns the file name extension.
+
+
+\membersection{wxFileName::GetForbiddenChars}\label{wxfilenamegetforbiddenchars}
+
+\func{static wxString}{GetForbiddenChars}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the characters that can't be used in filenames and directory names for the specified format.
+
 
 \membersection{wxFileName::GetFormat}\label{wxfilenamegetformat}
 
-\func{wxPathFormat}{GetFormat}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static wxPathFormat}{GetFormat}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-various helpers
-get the canonical path format for this platform
+Returns the canonical path format for this platform.
 
 
 \membersection{wxFileName::GetFullName}\label{wxfilenamegetfullname}
 
 \constfunc{wxString}{GetFullName}{\void}
 
+Returns the full name (including extension but excluding directories).
+
 
 \membersection{wxFileName::GetFullPath}\label{wxfilenamegetfullpath}
 
 \constfunc{wxString}{GetFullPath}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-add separator Construct full path with name and ext
+Returns the full path with name and extension.
 
 
 \membersection{wxFileName::GetHomeDir}\label{wxfilenamegethomedir}
 
-\func{wxString}{GetHomeDir}{\void}
+\func{static wxString}{GetHomeDir}{\void}
+
+Returns the home directory.
 
 
 \membersection{wxFileName::GetLongPath}\label{wxfilenamegetlongpath}
@@ -260,253 +422,472 @@ Return the long form of the path (returns identity on non-Windows platforms)
 
 \constfunc{wxDateTime}{GetModificationTime}{\void}
 
-convenience wrapper: get just the last mod time of the file
+Returns the last time the file was last modified.
 
 
 \membersection{wxFileName::GetName}\label{wxfilenamegetname}
 
 \constfunc{wxString}{GetName}{\void}
 
+Returns the name part of the filename.
+
 
 \membersection{wxFileName::GetPath}\label{wxfilenamegetpath}
 
-\constfunc{wxString}{GetPath}{\param{bool }{add\_separator = FALSE}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\constfunc{wxString}{GetPath}{\param{int }{flags = {\tt wxPATH\_GET\_VOLUME}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the path part of the filename (without the name or extension). The
+possible flags values are:
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxPATH\_GET\_VOLUME}}{Return the path with the volume (does
+nothing for the filename formats without volumes), otherwise the path without
+volume part is returned.}
+\twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing
+separator, if this flag is not given there will be no separator at the end of
+the path.}
+\end{twocollist}
+
+
+\membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator}
+
+\func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-Construct path only - possibly with the trailing separator
+Returns the usually used path separator for this format. For all formats but 
+{\tt wxPATH\_DOS} there is only one path separator anyhow, but for DOS there
+are two of them and the native one, i.e. the backslash is returned by this
+method.
+
+\wxheading{See also}
+
+\helpref{GetPathSeparators}{wxfilenamegetpathseparators}
 
 
 \membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators}
 
-\func{wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the string containing all the path separators for this format. For all
+formats but {\tt wxPATH\_DOS} this string contains only one character but for
+DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as
+separators.
 
-get the string of path separators for this format
+\wxheading{See also}
 
+\helpref{GetPathSeparator}{wxfilenamegetpathseparator}
 
-\membersection{wxFileName::GetPathWithSep}\label{wxfilenamegetpathwithsep}
 
-\constfunc{wxString}{GetPathWithSep}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\membersection{wxFileName::GetPathTerminators}\label{wxfilenamegetpathterminators}
 
-more readable synonym
+\func{static wxString}{GetPathTerminators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the string of characters which may terminate the path part. This is the
+same as \helpref{GetPathSeparators}{wxfilenamegetpathseparators} except for VMS
+path format where $]$ is used at the end of the path part.
 
 
 \membersection{wxFileName::GetShortPath}\label{wxfilenamegetshortpath}
 
 \constfunc{wxString}{GetShortPath}{\void}
 
-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::GetTimes}\label{wxfilenamegettimes}
 
-\constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtChange}}
+\constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}
+
+Returns the last access, last modification and creation times. The last access
+time is updated whenever the file is read or written (or executed in the case
+of Windows), last modification time is only changed when the file is written
+to. Finally, the creation time is indeed the time when the file was created
+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.
+
+Any of the pointers may be {\tt NULL} if the corresponding time is not
+needed.
 
-return the last access, last modification and last change times
-(any of the pointers may be NULL)
+\wxheading{Return value}
+
+{\tt true} on success, {\tt false} if we failed to retrieve the times.
 
 
 \membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume}
 
 \constfunc{wxString}{GetVolume}{\void}
 
+Returns the string containing the volume for this file name, empty if it
+doesn't have one or if the file system doesn't support volumes at all (for
+example, Unix).
+
 
 \membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
 
-\func{wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-get the string separating the volume from the path for this format
+Returns the string separating the volume from the path for this format.
 
 
 \membersection{wxFileName::HasExt}\label{wxfilenamehasext}
 
 \constfunc{bool}{HasExt}{\void}
 
+Returns {\tt true} if an extension is present.
+
 
 \membersection{wxFileName::HasName}\label{wxfilenamehasname}
 
 \constfunc{bool}{HasName}{\void}
 
+Returns {\tt true} if a name is present.
+
 
 \membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
 
 \constfunc{bool}{HasVolume}{\void}
 
+Returns {\tt true} if a volume specifier is present.
+
 
 \membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir}
 
-\func{void}{InsertDir}{\param{int }{before}, \param{const wxString\& }{dir}}
+\func{void}{InsertDir}{\param{size\_t }{before}, \param{const wxString\& }{dir}}
+
+Inserts a directory component before the zero-based position in the directory
+list. Please see \helpref{AppendDir}{wxfilenameappenddir} for important notes.
 
 
 \membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute}
 
 \func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-is this filename absolute?
+Returns {\tt true} if this filename is absolute.
 
 
 \membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive}
 
-\func{bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-Tests
-are the file names of this type cases sensitive?
+Returns {\tt true} if the file names of this type are case-sensitive.
 
 
 \membersection{wxFileName::IsOk}\label{wxfilenameisok}
 
 \constfunc{bool}{IsOk}{\void}
 
-file tests
-is the filename valid at all?
+Returns {\tt true} if the filename is valid, {\tt false} if it is not
+initialized yet. The assignment functions and
+\helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized,
+invalid state (the former only do it on failure).
 
 
 \membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator}
 
-\func{bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-is the char a path separator for this format?
+Returns {\tt true} if the char is a path separator for this format.
 
 
 \membersection{wxFileName::IsRelative}\label{wxfilenameisrelative}
 
 \func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-is this filename relative?
+Returns {\tt true} if this filename is not absolute.
 
 
-\membersection{wxFileName::IsWild}\label{wxfilenameiswild}
+\membersection{wxFileName::IsDir}\label{wxfilenameisdir}
 
-\func{bool}{IsWild}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\constfunc{bool}{IsDir}{\void}
 
-FIXME: what exactly does this do?
+Returns {\tt true} if this object represents a directory, {\tt false} otherwise
+(i.e. if it is a file). Note that this method doesn't test whether the
+directory or file really exists, you should use 
+\helpref{DirExists}{wxfilenamedirexists} or 
+\helpref{FileExists}{wxfilenamefileexists} for this.
 
+\membersection{wxFileName::MacFindDefaultTypeAndCreator}\label{wxfilenamemacfinddefaulttypeandcreator}
 
-\membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
+\func{static bool}{MacFindDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32* }{type}, \param{wxUint32* }{creator}}
+
+On Mac OS, gets the common type and creator for the given extension.
+
+\membersection{wxFileName::MacRegisterDefaultTypeAndCreator}\label{wxfilenamemacregisterdefaulttypeandcreator}
+
+\func{static void}{MacRegisterDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32 }{type}, \param{wxUint32 }{creator}}
+
+On Mac OS, registers application defined extensions and their default type and creator.
 
-\func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{bool }{full = FALSE}}
+\membersection{wxFileName::MacSetDefaultTypeAndCreator}\label{wxfilenamemacsetdefaulttypeandcreator}
 
-directory creation and removal.
-if full is TRUE, will try to make each directory in the path.
+\func{bool}{MacSetDefaultTypeAndCreator}{\void}
+
+On Mac OS, looks up the appropriate type and creator from the registration and then sets it.
+
+\membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute}
+
+\func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Make the file name absolute. This is a shortcut for
+{\tt \helpref{Normalize}{wxfilenamenormalize}(wxPATH\_NORM\_DOTS | wxPATH\_NORM\_ABSOLUTE | wxPATH\_NORM\_TILDE, cwd, format)}.
+
+\wxheading{See also}
+
+\helpref{MakeRelativeTo}{wxfilenamemakerelativeto},
+\helpref{Normalize}{wxfilenamenormalize},
+\helpref{IsAbsolute}{wxfilenameisabsolute}
+
+
+\membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto}
+
+\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+This function tries to put this file name in a form relative to {\it pathBase}.
+In other words, it returns the file name which should be used to access this
+file if the current directory were {\it pathBase}.
+
+\docparam{pathBase}{the directory to use as root, current directory is used by
+default}
+
+\docparam{format}{the file name format, native by default}
+
+\wxheading{Return value}
+
+{\tt true} if the file name has been changed, {\tt false} if we failed to do
+anything with it (currently this only happens if the file name is on a volume
+different from the volume specified by {\it pathBase}).
+
+\wxheading{See also}
+
+\helpref{Normalize}{wxfilenamenormalize}
 
 
 \membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
 
-\func{bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{bool }{full = FALSE}}
+\func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}}
+
+\func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}}
+
+\docparam{dir}{the directory to create}
+
+\docparam{parm}{the permissions for the newly created directory}
+
+\docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag,
+try to create each directory in the path and also don't return an error
+if the target directory already exists.}
+
+\wxheading{Return value}
+
+Returns {\tt true} if the directory was successfully created, {\tt false}
+otherwise.
 
 
 \membersection{wxFileName::Normalize}\label{wxfilenamenormalize}
 
-\func{bool}{Normalize}{\param{wxPathNormalize }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-operations on the path
-normalize the path: with the default flags value, the path will be
+Normalize the path. With the default flags value, the path will be
 made absolute, without any ".." and "." and all environment
-variables will be expanded in it
-this may be done using another (than current) value of cwd
+variables will be expanded in it.
+
+\docparam{flags}{The kind of normalization to do with the file name. It can be
+any or-combination of the following constants:
+
+\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\_CASE}}{if filesystem is case insensitive, transform to lower case}
+\twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute}
+\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\_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.}
+
+\docparam{format}{The file name format, native by default.}
 
 
 \membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}
 
 \func{void}{PrependDir}{\param{const wxString\& }{dir}}
 
+Prepends a directory to the file path. Please see 
+\helpref{AppendDir}{wxfilenameappenddir} for important notes.
+
+
 
 \membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir}
 
-\func{void}{RemoveDir}{\param{int }{pos}}
+\func{void}{RemoveDir}{\param{size\_t }{pos}}
 
+Removes the specified directory component from the path.
 
-\membersection{wxFileName::Rmdir}\label{wxfilenamermdir}
+\wxheading{See also}
 
-\func{bool}{Rmdir}{\void}
+\helpref{GetDirCount}{wxfilenamegetdircount}
+
+
+\membersection{wxFileName::RemoveLastDir}\label{wxfilenameremovelastdir}
+
+\func{void}{RemoveLastDir}{\void}
+
+Removes last directory component from the path.
 
 
 \membersection{wxFileName::Rmdir}\label{wxfilenamermdir}
 
-\func{bool}{Rmdir}{\param{const wxString\& }{dir}}
+\func{bool}{Rmdir}{\void}
+
+\func{static bool}{Rmdir}{\param{const wxString\& }{dir}}
+
+Deletes the specified directory from the file system.
 
 
 \membersection{wxFileName::SameAs}\label{wxfilenamesameas}
 
-\func{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
-compares with the rules of this platform
+Compares the filename using the rules of this platform.
 
 
 \membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
 
 \func{bool}{SetCwd}{\void}
 
-change the current working directory
-
-
-\membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
+\func{static bool}{SetCwd}{\param{const wxString\& }{cwd}}
 
-\func{bool}{SetCwd}{\param{const wxString\& }{cwd}}
+Changes the current working directory.
 
 
 \membersection{wxFileName::SetExt}\label{wxfilenamesetext}
 
 \func{void}{SetExt}{\param{const wxString\& }{ext}}
 
+Sets the extension of the file name. Setting an empty string
+as the extension will remove the extension resulting in a file 
+name without a trailing dot, unlike a call to 
+\helpref{SetEmptyExt}{wxfilenamesetemptyext}.
+
+\wxheading{See also}
+
+\helpref{SetEmptyExt}{wxfilenamesetemptyext}
+\helpref{ClearExt}{wxfilenameclearext}
+
+\membersection{wxFileName::SetEmptyExt}\label{wxfilenamesetemptyext}
+
+\func{void}{SetEmptyExt}{\void}
+
+Sets the extension of the file name to be an empty extension. 
+This is different from having no extension at all as the file 
+name will have a trailing dot after a call to this method.
+
+\wxheading{See also}
+
+\helpref{SetExt}{wxfilenamesetext}
+\helpref{ClearExt}{wxfilenameclearext}
 
 \membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname}
 
 \func{void}{SetFullName}{\param{const wxString\& }{fullname}}
 
-full name is the file name + extension (but without the path)
+The full name is the file name and extension (but without the path).
 
 
 \membersection{wxFileName::SetName}\label{wxfilenamesetname}
 
 \func{void}{SetName}{\param{const wxString\& }{name}}
 
+Sets the name.
+
 
 \membersection{wxFileName::SetTimes}\label{wxfilenamesettimes}
 
-\func{bool}{SetTimes}{\param{const wxDateTime* }{dtCreate}, \param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}}
+\func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}}
 
-set the file creation and last access/mod times
-(any of the pointers may be NULL)
+Sets the file creation and last access/modification times (any of the pointers may be NULL).
 
 
 \membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume}
 
 \func{void}{SetVolume}{\param{const wxString\& }{volume}}
 
+Sets the volume specifier.
+
 
 \membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath}
 
-\func{void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{bool }{*hasExt = \texttt{NULL}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+This function splits a full file name into components: the volume (with the
+first version) path (including the volume in the second version), the base name
+and the extension. Any of the output parameters ({\it volume}, {\it path}, 
+{\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the
+value of a particular component. Also, {\it fullpath} may be empty on entry.
+
+On return, {\it path} contains the file path (without the trailing separator), 
+{\it name} contains the file name and {\it ext} contains the file extension
+without leading dot. All three of them may be empty if the corresponding
+component is. The old contents of the strings pointed to by these parameters
+will be overwritten in any case (if the pointers are not {\tt NULL}).
+
+Note that for a filename ``foo.'' the extension is present, as indicated by the
+trailing dot, but empty. If you need to cope with such cases, you should use 
+\arg{hasExt} instead of relying on testing whether \arg{ext} is empty or not.
+
+
+\membersection{wxFileName::SplitVolume}\label{wxfilenamesplitvolume}
 
-\func{void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static void}{SplitVolume}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Splits the given \arg{fullpath} into the volume part (which may be empty) and
+the pure path part, not containing any volume.
+
+\wxheading{See also}
+
+\helpref{SplitPath}{wxfilenamesplitpath}
 
-split a fullpath into the volume, path, (base) name and extension
-(all of the pointers can be NULL)
 
 \membersection{wxFileName::Touch}\label{wxfilenametouch}
 
 \func{bool}{Touch}{\void}
 
-set the access and modification times to the current moment
+Sets the access and modification times to the current moment.
 
 
 \membersection{wxFileName::operator=}\label{wxfilenameoperatorassign}
 
 \func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}}
 
-
-\membersection{wxFileName::operator=}\label{wxfilenameoperatorassign}
-
 \func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}}
 
+Assigns the new value to this filename object.
+
 
 \membersection{wxFileName::operator==}\label{wxfilenameoperatorequal}
 
-\func{bool operator}{operator==}{\param{const wxFileName\& }{filename}}
+\constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}}
 
-uses the current platform settings
+\constfunc{bool operator}{operator==}{\param{const wxString\& }{filename}}
 
+Returns {\tt true} if the filenames are equal. The string {\it filenames} is
+interpreted as a path in the native filename format.
 
-\membersection{wxFileName::operator==}\label{wxfilenameoperatorequal}
 
-\func{bool operator}{operator==}{\param{const wxString\& }{filename}}
+\membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal}
+
+\constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}}
+
+\constfunc{bool operator}{operator!=}{\param{const wxString\& }{filename}}
+
+Returns {\tt true} if the filenames are different. The string {\it filenames}
+is interpreted as a path in the native filename format.
 
