ugh. Nesting the (per class) plugin sentries can require them to

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

diff --git a/docs/latex/wx/filename.tex b/docs/latex/wx/filename.tex
index 8f5ed744918cc3c0bbf6f12b37890be134e9ec73..36936b7d1cb437b2686cfedf936b7518605dd916 100644 (file)
--- a/docs/latex/wx/filename.tex
+++ b/docs/latex/wx/filename.tex
@@ -87,7 +87,10 @@ File names can be case-sensitive or not, the function\rtfsp
 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
 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}.
+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
 
 Other functions returning information about the file format provided by this
 class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp


@@ -173,7 +176,11 @@ 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}}
 
 
 \func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 

-Constructor 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}
 
 
 \membersection{wxFileName::AppendDir}\label{wxfilenameappenddir}
 


@@ -184,24 +191,12 @@ Constructor from a directory name, file base name and extension
 
 \func{void}{Assign}{\param{const wxFileName\& }{filepath}}
 
 
 \func{void}{Assign}{\param{const wxFileName\& }{filepath}}
 

-
-\membersection{wxFileName::Assign}\label{wxfilenameassign}
-

 \func{void}{Assign}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
 \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}}
 
 \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}}
 
 \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}}
 
 
 \func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
 


@@ -220,58 +215,78 @@ volume (or current volume if {\it volume} is empty).
 
 \func{void}{AssignDir}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 
 
 \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}
 
 
 \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}
 
 
 \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}
 
 
 \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.
+
+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}

 
 

-does the directory with this name exists?
+\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}
 
 
 \membersection{wxFileName::DirExists}\label{wxfilenamedirexists}
 

+\func{bool}{DirExists}{\void}
+

 \func{bool}{DirExists}{\param{const wxString\& }{dir}}
 
 \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::DirName}\label{wxfilenamedirname}
 
 \func{wxFileName}{DirName}{\param{const wxString\& }{dir}}
 

-

 \membersection{wxFileName::FileExists}\label{wxfilenamefileexists}
 
 \func{bool}{FileExists}{\void}
 
 \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}}
 
 \func{bool}{FileExists}{\param{const wxString\& }{file}}
 

+Does the file with this name exists?

 
 \membersection{wxFileName::FileName}\label{wxfilenamefilename}
 
 
 \membersection{wxFileName::FileName}\label{wxfilenamefilename}
 


@@ -279,7 +294,6 @@ does the file with this name exists?
 
 static pseudo constructors
 
 
 static pseudo constructors
 

-

 \membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd}
 
 \func{wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}
 \membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd}
 
 \func{wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}


@@ -443,23 +457,22 @@ are the file names of this type cases sensitive?
 
 \constfunc{bool}{IsOk}{\void}
 
 
 \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}}
 
 
 \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}}
 
 
 \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::IsWild}\label{wxfilenameiswild}
 


@@ -467,6 +480,28 @@ is this filename relative?
 
 FIXME: what exactly does this do?
 
 
 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}
 
 
 \membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}