%% Created: 30.11.01
%% RCS-ID: $Id$
%% Copyright: (c) 2001 Vadim Zeitlin
-%% License: wxWidgets license
+%% License: wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\class{wxFileName}}\label{wxfilename}
No base class
+\wxheading{Include files}
+
+<wx/filename.h>
+
\wxheading{Data structures}
Many wxFileName methods accept the path format argument which is by\rtfsp
\latexignore{\rtfignore{\wxheading{Function groups}}}
-\membersection{File name format}
+\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
\helpref{IsRelative}{wxfilenameisrelative}
-\membersection{File name construction}
+\membersection{File name construction}\label{filenameconstruction}
TODO.
-\membersection{File tests}
+\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,
or \helpref{$==$}{wxfilenameoperatorequal}.
-\membersection{File name components}
+\membersection{File name components}\label{filenamecomponents}
-These functions allow to examine and modify the directories of the path:
+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{RemoveDir}{wxfilenameremovedir}\\
+\helpref{RemoveLastDir}{wxfilenameremovelastdir}
To change the components of the file name individually you can use the
following functions:
\helpref{HasName}{wxfilenamehasname}\\
\helpref{HasVolume}{wxfilenamehasvolume}\\
\helpref{SetExt}{wxfilenamesetext}\\
+\helpref{ClearExt}{wxfilenameclearext}\\
+\helpref{SetEmptyExt}{wxfilenamesetemptyext}\\
\helpref{SetName}{wxfilenamesetname}\\
\helpref{SetVolume}{wxfilenamesetvolume}\\
-\membersection{Operations}
+\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
\func{void}{Assign}{\param{const wxString\& }{fullpath}, \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{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}}
\func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
Reset all components to default, uninitialized state.
+\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}}}
\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 programs current working directory is returned for the
+the volume is empty, the program's current working directory is returned for the
current volume.
\wxheading{Return value}
\constfunc{wxString}{GetName}{\void}
-Returns the name part of the filename.
+Returns the name part of the filename (without extension).
+
+\wxheading{See also}
+
+\helpref{GetFullName}{wxfilenamegetfullname}
+
\membersection{wxFileName::GetPath}\label{wxfilenamegetpath}
\helpref{GetPathSeparator}{wxfilenamegetpathseparator}
+\membersection{wxFileName::GetPathTerminators}\label{wxfilenamegetpathterminators}
+
+\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}
\constfunc{wxString}{GetVolume}{\void}
-Returns the string containing the volume for this file name, mepty if it
+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::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.
\helpref{DirExists}{wxfilenamedirexists} or
\helpref{FileExists}{wxfilenamefileexists} for this.
+\membersection{wxFileName::MacFindDefaultTypeAndCreator}\label{wxfilenamemacfinddefaulttypeandcreator}
+
+\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.
+
+\membersection{wxFileName::MacSetDefaultTypeAndCreator}\label{wxfilenamemacsetdefaulttypeandcreator}
+
+\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}
\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 tolower 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\_LONG}}{make the path the long form}
\twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)}
\membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir}
-\func{void}{RemoveDir}{\param{int }{pos}}
+\func{void}{RemoveDir}{\param{size\_t }{pos}}
-Removes a directory name.
+Removes the specified directory component from the path.
+
+\wxheading{See also}
+
+\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{void}{SetExt}{\param{const wxString\& }{ext}}
-Sets the extension of this file name.
+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}{SetName}{\param{const wxString\& }{name}}
-Sets the name.
+Sets the name part (without extension).
+
+\wxheading{See also}
+
+\helpref{SetFullName}{wxfilenamesetfullname}
\membersection{wxFileName::SetTimes}\label{wxfilenamesettimes}
\membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath}
+\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}}
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{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}
+
\membersection{wxFileName::Touch}\label{wxfilenametouch}
projects / wxWidgets.git / blobdiff