X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2569938d392eace21ae617355f9c1a636185f36f..60b73526d6797ee466c272dbfca962a230bc5908:/docs/latex/wx/filename.tex diff --git a/docs/latex/wx/filename.tex b/docs/latex/wx/filename.tex index 992aead482..36936b7d1c 100644 --- a/docs/latex/wx/filename.tex +++ b/docs/latex/wx/filename.tex @@ -65,42 +65,122 @@ enum wxPathNormalize } \end{verbatim} +\latexignore{\rtfignore{\wxheading{Function groups}}} + +\membersection{File name format} + +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 sam 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{Normalize}{wxfilenamenormalize}. 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} and\rtfsp +\helpref{IsWild}{wxfilenameiswild}. + +\helpref{IsRelative}{wxfilenameisrelative} + +\membersection{File name construction} + +TODO. + +\membersection{File tests} + +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} + +These functions allow to examine and modify the directories of the path: + +\helpref{AppendDir}{wxfilenameappenddir}\\ +\helpref{InsertDir}{wxfilenameinsertdir}\\ +\helpref{GetDirCount}{wxfilenamegetdircount} +\helpref{PrependDir}{wxfilenameprependdir}\\ +\helpref{RemoveDir}{wxfilenameremovedir} + +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{SetName}{wxfilenamesetname}\\ +\helpref{SetVolume}{wxfilenamesetvolume}\\ + +\membersection{Operations} + +These methods allow to work with the file creation, access and modification +times: + +\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 +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} - \func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -from a directory name and a file name - - -\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename3} +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}} -from a directory name, file base name and extension +Constructor from a directory name, base file name and extension + +\func{}{wxFileName}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} +Constructor from a volume name, a directory name, base file name and extension \membersection{wxFileName::AppendDir}\label{wxfilenameappenddir} @@ -111,91 +191,102 @@ from a directory name, file base name and extension \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{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}} \membersection{wxFileName::AssignCwd}\label{wxfilenameassigncwd} -\func{void}{AssignCwd}{\void} +\func{void}{AssignCwd}{\param{const wxString\& }{volume = ""}} + +Makes this object refer to the current working directory on the specified +volume (or current volume if {\it volume} is empty). -various file/dir operations -retrieve the value of the current working directory +\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 - +Set 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) - +Set this file name object to the home directory. \membersection{wxFileName::AssignTempFileName}\label{wxfilenameassigntempfilename} -\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}} - -get a temp file name starting with thespecified prefix +\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}} +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::CreateTempFileName}\label{wxfilenamecreatetempfilename} -\membersection{wxFileName::DirExists}\label{wxfilenamedirexists} +\func{static wxString}{CreateTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}} -\func{bool}{DirExists}{\void} +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. -does the directory with this name exists? +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} + +\docparam{fileTemp}{The file to open or {\tt NULL} to just get the name} + +\wxheading{Return value} + +The full temporary file name or an empty string on error. \membersection{wxFileName::DirExists}\label{wxfilenamedirexists} +\func{bool}{DirExists}{\void} + \func{bool}{DirExists}{\param{const wxString\& }{dir}} +Does the directory with this name exists? \membersection{wxFileName::DirName}\label{wxfilenamedirname} \func{wxFileName}{DirName}{\param{const wxString\& }{dir}} - \membersection{wxFileName::FileExists}\label{wxfilenamefileexists} \func{bool}{FileExists}{\void} -does the file with this name exists? - - -\membersection{wxFileName::FileExists}\label{wxfilenamefileexists} - \func{bool}{FileExists}{\param{const wxString\& }{file}} +Does the file with this name exists? \membersection{wxFileName::FileName}\label{wxfilenamefilename} @@ -203,11 +294,22 @@ does the file with this name exists? static pseudo constructors - \membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd} -\func{wxString}{GetCwd}{\void} +\func{wxString}{GetCwd}{\param{const wxString\& }{volume = ""}} + +Retrieve 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 +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} @@ -355,23 +457,22 @@ are the file names of this type cases sensitive? \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}} -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} @@ -379,19 +480,45 @@ is this filename relative? FIXME: what exactly does this do? +\membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto} + +\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = ""}, \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{int }{perm = 0777}, \param{bool }{full = FALSE}} -directory creation and removal. -if full is TRUE, will try to make each directory in the path. +\func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{bool }{full = FALSE}} +\docparam{dir}{the directory to create} -\membersection{wxFileName::Mkdir}\label{wxfilenamemkdir} +\docparam{parm}{the permissions for the newly created directory} -\func{bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{bool }{full = FALSE}} +\docparam{full}{if {\tt TRUE}, will try to make each directory in the path} +\wxheading{Return value} + +Returns {\tt TRUE} if the directory was successfully created, {\tt FALSE} +otherwise. \membersection{wxFileName::Normalize}\label{wxfilenamenormalize} @@ -418,30 +545,25 @@ this may be done using another (than current) value of cwd \func{bool}{Rmdir}{\void} +\func{static bool}{Rmdir}{\param{const wxString\& }{dir}} -\membersection{wxFileName::Rmdir}\label{wxfilenamermdir} - -\func{bool}{Rmdir}{\param{const wxString\& }{dir}} +Deletes the specified directory. \membersection{wxFileName::SameAs}\label{wxfilenamesameas} \func{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{bool}{SetCwd}{\param{const wxString\& }{cwd}} +\func{static bool}{SetCwd}{\param{const wxString\& }{cwd}} +change the current working directory \membersection{wxFileName::SetExt}\label{wxfilenamesetext} @@ -493,20 +615,15 @@ set the access and modification times to the current moment \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}} -uses the current platform settings - - -\membersection{wxFileName::operator==}\label{wxfilenameoperatorequal} - \func{bool operator}{operator==}{\param{const wxString\& }{filename}} +Returns {\tt TRUE} if the filenames are equal for the native file format. +