X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a44f3b5a890fbb2a88ef9adafd94f662e1664889..107ea8f0694830232c7df4a1568b707111c04649:/interface/wx/filename.h diff --git a/interface/wx/filename.h b/interface/wx/filename.h index 4917fecce9..97fd9b6822 100644 --- a/interface/wx/filename.h +++ b/interface/wx/filename.h @@ -7,7 +7,8 @@ ///////////////////////////////////////////////////////////////////////////// -/** The various values for the path format: this mainly affects the path +/** + The various values for the path format: this mainly affects the path separator but also whether or not the path has the drive part (as under Windows). @@ -28,19 +29,27 @@ enum wxPathFormat }; -/** The kind of normalization to do with the file name: these values can be +/** + The kind of normalization to do with the file name: these values can be or'd together to perform several operations at once. See wxFileName::Normalize() for more info. */ enum wxPathNormalize { - wxPATH_NORM_ENV_VARS = 0x0001, //!< replace env vars with their values. - wxPATH_NORM_DOTS = 0x0002, //!< squeeze all .. and . and prepend cwd. - wxPATH_NORM_TILDE = 0x0004, //!< Unix only: replace ~ and ~user. - wxPATH_NORM_CASE = 0x0008, //!< if case insensitive => tolower. - wxPATH_NORM_ABSOLUTE = 0x0010, //!< make the path absolute. - wxPATH_NORM_LONG = 0x0020, //!< make the path the long form. - wxPATH_NORM_SHORTCUT = 0x0040, //!< resolve the shortcut, if it is a shortcut. + //! Replace environment variables with their values. + //! wxFileName understands both Unix and Windows (but only under Windows) environment + //! variables expansion: i.e. @c "$var", @c "$(var)" and @c "${var}" are always understood + //! and in addition under Windows @c "%var%" is also. + wxPATH_NORM_ENV_VARS = 0x0001, + + wxPATH_NORM_DOTS = 0x0002, //!< Squeeze all @c ".." and @c "." and prepend the current working directory. + wxPATH_NORM_TILDE = 0x0004, //!< Replace @c "~" and @c "~user" (Unix only). + wxPATH_NORM_CASE = 0x0008, //!< If the platform is case insensitive, make lowercase the path. + wxPATH_NORM_ABSOLUTE = 0x0010, //!< Make the path absolute. + wxPATH_NORM_LONG = 0x0020, //!< Expand the path to the "long" form (Windows only). + wxPATH_NORM_SHORTCUT = 0x0040, //!< Resolve the shortcut, if it is a shortcut (Windows only). + + //! A value indicating all normalization flags except for @c wxPATH_NORM_CASE. wxPATH_NORM_ALL = 0x00ff & ~wxPATH_NORM_CASE }; @@ -148,6 +157,7 @@ wxULongLong wxInvalidSize; @li wxFileName::AssignCwd() @li wxFileName::AssignDir() @li wxFileName::AssignHomeDir() + @li wxFileName::AssignTempFileName() @li wxFileName::DirName() @li wxFileName::FileName() @li wxFileName::operator=() @@ -320,7 +330,7 @@ public: @see GetCwd() */ - static void AssignCwd(const wxString& volume = wxEmptyString); + void AssignCwd(const wxString& volume = wxEmptyString); /** Sets this file name object to the given directory name. @@ -334,17 +344,32 @@ public: */ void AssignHomeDir(); - //@{ /** The function calls CreateTempFileName() 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 - an invalid state (see IsOk()) + an invalid state (see IsOk()). + */ + void AssignTempFileName(const wxString& prefix); + + /** + The function calls CreateTempFileName() to create a temporary + file name and open @a fileTemp with it. + + If the file couldn't be opened, the object is put into + an invalid state (see IsOk()). */ void AssignTempFileName(const wxString& prefix, wxFile* fileTemp); + + /** + The function calls CreateTempFileName() to create a temporary + file name and open @a fileTemp with it. + + If the file couldn't be opened, the object is put into + an invalid state (see IsOk()). + */ void AssignTempFileName(const wxString& prefix, wxFFile* fileTemp); - //@} /** Reset all components to default, uninitialized state. @@ -359,6 +384,7 @@ public: */ void ClearExt(); + //@{ /** Returns a temporary file name starting with the given @e prefix. If the @a prefix is an absolute path, the temporary file is created in this @@ -383,6 +409,9 @@ public: */ static wxString CreateTempFileName(const wxString& prefix, wxFile* fileTemp = NULL); + static wxString CreateTempFileName(const wxString& prefix, + wxFFile* fileTemp = NULL); + //@} /** Returns @true if the directory with this name exists. @@ -522,7 +551,7 @@ public: The possible flags values are: - - @b wxPATH_GET_VOLUME + - @b wxPATH_GET_VOLUME: Return the path with the volume (does nothing for the filename formats without volumes), otherwise the path without volume part is returned. @@ -546,7 +575,7 @@ public: @see GetPathSeparators() */ - static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); + static wxUniChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); /** Returns the string containing all the path separators for this format. @@ -592,7 +621,7 @@ public: not be read (because e.g. the file is locked by another process) the returned value is ::wxInvalidSize. */ - const static wxULongLong GetSize(const wxString& filename); + static wxULongLong GetSize(const wxString& filename); /** Returns the directory used for temporary files. @@ -873,7 +902,7 @@ public: @param flags The kind of normalization to do with the file name. It can be - any or-combination of the wxPathNormalize enumeration values. + any or-combination of the ::wxPathNormalize enumeration values. @param cwd If not empty, this directory will be used instead of current working directory in normalization (see @c wxPATH_NORM_ABSOLUTE). @@ -904,6 +933,53 @@ public: */ void RemoveLastDir(); + /** + If the path contains the value of the environment variable named @a envname + then this function replaces it with the string obtained from + wxString::Format(replacementFmtString, value_of_envname_variable). + + This function is useful to make the path shorter or to make it dependent + from a certain environment variable. + Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this + function (depending on the value of @a replacementFmtString). + + The name and extension of this filename are not modified. + + Example: + @code + wxFileName fn("/usr/openwin/lib/someFile"); + fn.ReplaceEnvVariable("OPENWINHOME"); + // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile" + @endcode + + @since 2.9.0 + + @return @true if the operation was successful (which doesn't mean + that something was actually replaced, just that ::wxGetEnv + didn't fail). + */ + bool ReplaceEnvVariable(const wxString& envname, + const wxString& replacementFmtString = "$%s", + wxPathFormat format = wxPATH_NATIVE); + + /** + Replaces, if present in the path, the home directory for the given user + (see ::wxGetHomeDir) with a tilde (~). + + Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this + function. + + The name and extension of this filename are not modified. + + @since 2.9.0 + + @return @true if the operation was successful (which doesn't mean + that something was actually replaced, just that ::wxGetHomeDir + didn't fail). + */ + bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE); + + /** Deletes the specified directory from the file system. */ @@ -994,18 +1070,19 @@ public: trailing dot, but empty. If you need to cope with such cases, you should use @a hasExt instead of relying on testing whether @a ext is empty or not. */ - static void SplitPath(const wxString& fullpath, wxString* volume, + static void SplitPath(const wxString& fullpath, + wxString* volume, wxString* path, wxString* name, wxString* ext, - bool hasExt = NULL, + bool* hasExt = NULL, wxPathFormat format = wxPATH_NATIVE); static void SplitPath(const wxString& fullpath, wxString* volume, wxString* path, wxString* name, wxString* ext, - wxPathFormat format = wxPATH_NATIVE); + wxPathFormat format); static void SplitPath(const wxString& fullpath, wxString* path, wxString* name,