X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/992ff3310e25b3cfa91685e04e38f28d1b36f262..600e986ad79fa72b8eb02ac4c30f8db087e0a123:/interface/wx/filename.h?ds=sidebyside

diff --git a/interface/wx/filename.h b/interface/wx/filename.h
index 8b97fea016..774c6b76df 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
 };
 
@@ -538,7 +547,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.
 
@@ -920,6 +929,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.
     */