diff --git a/docs/latex/wx/pathlist.tex b/docs/latex/wx/pathlist.tex index e1e90aa3fd..934f0170d2 100644 --- a/docs/latex/wx/pathlist.tex +++ b/docs/latex/wx/pathlist.tex @@ -2,12 +2,10 @@ The path list is a convenient way of storing a number of directories, and when presented with a filename without a directory, searching for an existing file -in those directories. Storing the filename only in an application's files and -using a locally-defined list of directories makes the application and its files more -portable. +in those directories. -Use the \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} global function -to extract the filename from the path. +Be sure to look also at \helpref{wxStandardPaths}{wxstandardpaths} if you only +want to search files in some standard paths. \wxheading{Derived from} @@ -40,17 +38,19 @@ Constructs the object calling the \helpref{Add}{wxpathlistadd} function. \func{void}{AddEnvList}{\param{const wxString\& }{env\_variable}} Finds the value of the given environment variable, and adds all paths -to the path list. Useful for finding files in the PATH variable, for +to the path list. Useful for finding files in the {\tt PATH} variable, for example. \membersection{wxPathList::Add}\label{wxpathlistadd} -\func{void}{Add}{\param{const wxString\& }{path}} +\func{bool}{Add}{\param{const wxString\& }{path}} \func{void}{Add}{\param{const wxArrayString\& }{arr}} The first form adds the given directory to the path list, if the path is not already in the list. +If the path cannot be normalized for some reason, it returns \false. + The second form just calls the first form on all elements of the given array. The {\it path} is always considered a directory but no existence checks will be done on it @@ -63,34 +63,42 @@ The {\it path} is always considered a directory but no existence checks will be \membersection{wxPathList::EnsureFileAccessible}\label{wxpathlistensurefileaccessible} -\func{void}{EnsureFileAccessible}{\param{const wxString\& }{filename}} +\func{bool}{EnsureFileAccessible}{\param{const wxString\& }{filename}} -Given a full filename (with path), ensures that files in the same path -can be accessed using the pathlist. It does this by stripping the -filename and adding the path to the list if not already there. +Given a full filename (with path), ensures that the file exists and +then calls \helpref{Add}{wxpathlistadd} with the path of the file. + +Returns \false if the file does not exist (and in this case its path won't be added). \membersection{wxPathList::FindAbsoluteValidPath}\label{wxpathlistfindabsolutepath} \constfunc{wxString}{FindAbsoluteValidPath}{\param{const wxString\& }{file}} -Searches for a full (i.e. absolute) path for an existing file by appending {\it file} to -successive members of the path list. If the file wasn't found, an empty -string is returned. +Like \helpref{FindValidPath}{wxpathlistfindvalidpath} but this function always +returns an absolute path (eventually prepending the current working directory +to the value returned \helpref{FindValidPath}{wxpathlistfindvalidpath}) or an +empty string. \membersection{wxPathList::FindValidPath}\label{wxpathlistfindvalidpath} \constfunc{wxString}{FindValidPath}{\param{const wxString\& }{file}} -Searches for a path for an existing file by appending {\it file} to -successive members of the path list. -If the file wasn't found, an empty string is returned. +Searches the given file in all paths stored in this class. +The first path which concatenated to the given string points to an existing +file (see \helpref{wxFileExists}{wxfileexists}) is returned. -The returned path may be relative to the current working directory. +If the file wasn't found in any of the stored paths, an empty string is returned. The given string must be a file name, eventually with a path prefix (if the path prefix is absolute, only its name will be searched); i.e. it must not end with a directory separator (see \helpref{wxFileName::GetPathSeparator}{wxfilenamegetpathseparator}) otherwise an assertion will fail. +The returned path may be relative to the current working directory. +Note in fact that wxPathList can be used to store both relative and absolute paths so that +if you \helpref{Add()}{wxpathlistadd}ed relative paths, then the current working directory +(see \helpref{wxGetCwd}{wxgetcwd} and \helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}) +may affect the value returned by this function! + diff --git a/include/wx/filefn.h b/include/wx/filefn.h index c2d5eeec3a..67fae5e069 100644 --- a/include/wx/filefn.h +++ b/include/wx/filefn.h @@ -669,7 +669,7 @@ public: void AddEnvList(const wxString& envVariable); // Adds given path to this list - void Add(const wxString& path); + bool Add(const wxString& path); void Add(const wxArrayString &paths); // Find the first full path for which the file exists @@ -680,10 +680,12 @@ public: wxString FindAbsoluteValidPath(const wxString& filename) const; // Given full path and filename, add path to list - void EnsureFileAccessible(const wxString& path); + bool EnsureFileAccessible(const wxString& path); +#if WXWIN_COMPATIBILITY_2_6 // Returns true if the path is in the list wxDEPRECATED( bool Member(const wxString& path) const ); +#endif }; #endif // _WX_FILEFN_H_ diff --git a/src/common/filefn.cpp b/src/common/filefn.cpp index bdfd37b1a7..d690e66d9d 100644 --- a/src/common/filefn.cpp +++ b/src/common/filefn.cpp @@ -156,7 +156,7 @@ WXDLLEXPORT int wxOpen( const wxChar *pathname, int flags, mode_t mode ) // wxPathList // ---------------------------------------------------------------------------- -void wxPathList::Add(const wxString& path) +bool wxPathList::Add(const wxString& path) { // add a path separator to force wxFileName to interpret it always as a directory // (i.e. if we are called with '/home/user' we want to consider it a folder and @@ -164,11 +164,17 @@ void wxPathList::Add(const wxString& path) wxFileName fn(path + wxFileName::GetPathSeparator()); // add only normalized relative/absolute paths - fn.Normalize(wxPATH_NORM_DOTS|wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS); + // NB: we won't do wxPATH_NORM_DOTS in order to avoid problems when trying to + // normalize paths which starts with ".." (which can be normalized only if + // we use also wxPATH_NORM_ABSOLUTE - which we don't want to use). + if (!fn.Normalize(wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS)) + return false; wxString toadd = fn.GetPath(); if (Index(toadd) == wxNOT_FOUND) wxArrayString::Add(toadd); // do not add duplicates + + return true; } void wxPathList::Add(const wxArrayString &arr) @@ -207,21 +213,17 @@ void wxPathList::AddEnvList (const wxString& WXUNUSED_IN_WINCE(envVariable)) // Given a full filename (with path), ensure that that file can // be accessed again USING FILENAME ONLY by adding the path // to the list if not already there. -void wxPathList::EnsureFileAccessible (const wxString& path) +bool wxPathList::EnsureFileAccessible (const wxString& path) { - wxString path_only(wxPathOnly(path)); - if ( !path_only.empty() ) - { - if ( Index(path_only) == wxNOT_FOUND ) - Add(path_only); - } + return Add(wxPathOnly(path)); } -// deprecated ! +#if WXWIN_COMPATIBILITY_2_6 bool wxPathList::Member (const wxString& path) const { return Index(path) != wxNOT_FOUND; } +#endif wxString wxPathList::FindValidPath (const wxString& file) const { @@ -230,8 +232,13 @@ wxString wxPathList::FindValidPath (const wxString& file) const wxFileName fn(file); wxString strend; - // NB: normalize without making absolute ! - fn.Normalize(wxPATH_NORM_DOTS|wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS); + // NB: normalize without making absolute otherwise calling this function with + // e.g. "b/c.txt" would result in removing the directory 'b' and the for loop + // below would only add to the paths of this list the 'c.txt' part when doing + // the existence checks... + // NB: we don't use wxPATH_NORM_DOTS here, too (see wxPathList::Add for more info) + if (!fn.Normalize(wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS)) + return wxEmptyString; wxASSERT_MSG(!fn.IsDir(), wxT("Cannot search for directories; only for files")); if (fn.IsAbsolute())