don't make read-only text controls editable when enabled

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

diff --git a/docs/latex/wx/filename.tex b/docs/latex/wx/filename.tex
index b7c8e658f0774196d6d34b2516f39a288f8823b5..2ec4d49ad60abf66774f67c61d90952675ef2f62 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.
 
+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
@@ -101,6 +142,8 @@ You can initialize a wxFileName instance using one of the following functions:
 \helpref{AssignDir}{wxfilenameassigndir}\\
 \helpref{AssignHomeDir}{wxfilenameassignhomedir}\\
 \helpref{AssignHomeTempFileName}{wxfilenameassigntempfilename}\\
+\helpref{DirName}{wxfilenamedirname}\\
+\helpref{FileName}{wxfilenamefilename}\\
 \helpref{operator $=$}{wxfilenameoperatorassign}
 
 
@@ -575,6 +618,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.
 
+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.
 
@@ -815,20 +864,25 @@ 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\_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\_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\_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
-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}