Make wxTopLevelWindow::GetDefaultSize() public and document it.

[wxWidgets.git] / interface / wx / filename.h

diff --git a/interface/wx/filename.h b/interface/wx/filename.h
index a9150f9a27adc666db2e005049f795fca3c2aeb5..cadedb661be2f05051e4e8f83d5c5981969a64b1 100644 (file)
--- a/interface/wx/filename.h
+++ b/interface/wx/filename.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxFileName
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxFileName
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -28,6 +28,25 @@ enum wxPathFormat
     wxPATH_MAX   //!< Not a valid value for specifying path format
 };
 
     wxPATH_MAX   //!< Not a valid value for specifying path format
 };
 

+/**
+    Different conventions for human readable sizes.
+
+    @see wxFileName::GetHumanReadableSize().
+
+    @since 2.9.1
+*/
+enum wxSizeConvention
+{
+    /// 1024 bytes = 1KB.
+    wxSIZE_CONV_TRADITIONAL,
+
+    /// 1024 bytes = 1KiB.
+    wxSIZE_CONV_IEC,
+
+    /// 1000 bytes = 1KB.
+    wxSIZE_CONV_SI
+};
+

 
 /**
     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


@@ -36,8 +55,13 @@ enum wxPathFormat
 */
 enum wxPathNormalize
 {
 */
 enum wxPathNormalize
 {

-    wxPATH_NORM_ENV_VARS = 0x0001,  //!< Replace environment variables with their values.
-    wxPATH_NORM_DOTS     = 0x0002,  //!< Squeeze all @c ".." and @c "." and prepend the current working directory.
+    //! 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 ".".

     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_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.


@@ -48,6 +72,24 @@ enum wxPathNormalize
     wxPATH_NORM_ALL      = 0x00ff & ~wxPATH_NORM_CASE
 };
 
     wxPATH_NORM_ALL      = 0x00ff & ~wxPATH_NORM_CASE
 };
 

+/**
+    Flags for wxFileName::Rmdir().
+ */
+enum
+{
+    /// Delete the specified directory and its subdirectories if they are empty.
+    wxPATH_RMDIR_FULL = 1,
+
+    /**
+      Delete the specified directory and all the files and subdirectories in it
+      recursively.
+
+      This flag is obviously @b dangerous and should be used with care and
+      after asking the user for confirmation.
+     */
+    wxPATH_RMDIR_RECURSIVE = 2
+};
+

 /**
     The return value of wxFileName::GetSize() in case of error.
 */
 /**
     The return value of wxFileName::GetSize() in case of error.
 */


@@ -325,7 +367,7 @@ public:
 
         @see GetCwd()
     */
 
         @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.
 
     /**
         Sets this file name object to the given directory name.


@@ -379,6 +421,7 @@ public:
     */
     void ClearExt();
 
     */
     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
     /**
         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


@@ -403,6 +446,9 @@ public:
     */
     static wxString CreateTempFileName(const wxString& prefix,
                                        wxFile* fileTemp = NULL);
     */
     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.
 
     /**
         Returns @true if the directory with this name exists.


@@ -410,7 +456,7 @@ public:
     bool DirExists() const;
 
     /**
     bool DirExists() const;
 
     /**

-        Returns @true if the directory with this name exists.
+        Returns @true if the directory with name @a dir exists.

     */
     static bool DirExists(const wxString& dir);
 
     */
     static bool DirExists(const wxString& dir);
 


@@ -429,7 +475,7 @@ public:
     bool FileExists() const;
 
     /**
     bool FileExists() const;
 
     /**

-        Returns @true if the file with this name exists.
+        Returns @true if the file with name @a file exists.

 
         @see DirExists()
     */
 
         @see DirExists()
     */


@@ -495,30 +541,41 @@ public:
     */
     static wxString GetHomeDir();
 
     */
     static wxString GetHomeDir();
 

+    //@{

     /**
     /**

-        Returns the size of the file in a human-readable form.
-
-        If the size could not be retrieved the @c failmsg string
-        is returned. In case of success, the returned string is
-        a floating-point number with @c precision decimal digits
-        followed by the size unit (B, kB, MB, GB, TB: respectively
-        bytes, kilobytes, megabytes, gigabytes, terabytes).
-    */
-    wxString GetHumanReadableSize(const wxString& failmsg = "Not available",
-                                  int precision = 1) const;
-
-    /**
-        Returns the size of the given number of bytes in a human-readable form.
-
-        If @a bytes is ::wxInvalidSize or zero, then @a nullsize is returned.
-
-        In case of success, the returned string is a floating-point number with
-        @a precision decimal digits followed by the size unit (B, kB, MB, GB,
-        TB: respectively bytes, kilobytes, megabytes, gigabytes, terabytes).
-    */
-    static wxString GetHumanReadableSize(const wxULongLong& bytes,
-                                         const wxString& nullsize = "Not available",
-                                         int precision = 1);
+        Returns the representation of the file size in a human-readable form.
+
+        In the first version, the size of this file is used. In the second one,
+        the specified size @a bytes is used.
+
+        If the file size could not be retrieved or @a bytes is ::wxInvalidSize
+        or zero, the @c failmsg string is returned.
+
+        Otherwise the returned string is a floating-point number with @c
+        precision decimal digits followed by the abbreviation of the unit used.
+        By default the traditional, although incorrect, convention of using SI
+        units for multiples of 1024 is used, i.e. returned string will use
+        suffixes of B, KB, MB, GB, TB for bytes, kilobytes, megabytes,
+        gigabytes and terabytes respectively. With the IEC convention the names
+        of the units are changed to B, KiB, MiB, GiB and TiB fofr bytes,
+        kibibytes, mebibyes, gibibytes and tebibytes. Finally, with SI
+        convention the same B, KB, MB, GB and TB suffixes are used but in their
+        correct SI meaning, i.e. as multiples of 1000 and not 1024.
+
+        Support for the different size conventions is new in wxWidgets 2.9.1,
+        in previous versions only the traditional convention was implemented.
+    */
+    wxString
+    GetHumanReadableSize(const wxString& failmsg = _("Not available"),
+                         int precision = 1,
+                         wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL) const;
+
+    static wxString
+    GetHumanReadableSize(const wxULongLong& bytes,
+                         const wxString& nullsize = _("Not available"),
+                         int precision = 1,
+                         wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL);
+    //@}

 
     /**
         Return the long form of the path (returns identity on non-Windows platforms).
 
     /**
         Return the long form of the path (returns identity on non-Windows platforms).


@@ -612,7 +669,7 @@ public:
         not be read (because e.g. the file is locked by another process) the returned
         value is ::wxInvalidSize.
     */
         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.
 
     /**
         Returns the directory used for temporary files.


@@ -792,6 +849,24 @@ public:
     static bool IsPathSeparator(wxChar ch,
                                 wxPathFormat format = wxPATH_NATIVE);
 
     static bool IsPathSeparator(wxChar ch,
                                 wxPathFormat format = wxPATH_NATIVE);
 

+    /**
+        Returns @true if the volume part of the path is a unique volume name.
+
+        This function will always return @false if the path format is not
+        wxPATH_DOS.
+
+        Unique volume names are Windows volume identifiers which remain the same
+        regardless of where the volume is actually mounted. Example of a path
+        using a volume name could be
+        @code
+            \\?\Volume{8089d7d7-d0ac-11db-9dd0-806d6172696f}\Program Files\setup.exe
+        @endcode
+
+        @since 2.9.1
+    */
+    static bool IsMSWUniqueVolumeNamePath(const wxString& path,
+                                          wxPathFormat format = wxPATH_NATIVE);
+

     /**
         Returns @true if this filename is not absolute.
     */
     /**
         Returns @true if this filename is not absolute.
     */


@@ -865,7 +940,7 @@ public:
         @return Returns @true if the directory was successfully created, @false
                 otherwise.
     */
         @return Returns @true if the directory was successfully created, @false
                 otherwise.
     */

-    bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0);
+    bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0) const;

 
     /**
         Creates a directory.
 
     /**
         Creates a directory.


@@ -924,15 +999,80 @@ public:
     */
     void RemoveLastDir();
 
     */
     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.
     /**
         Deletes the specified directory from the file system.

+
+        @param flags
+            Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
+            default contains neither so the directory will not be removed
+            unless it is empty.
+
+        @return Returns @true if the directory was successfully deleted, @false
+                otherwise.

     */
     */

-    bool Rmdir();
+    bool Rmdir(int flags = 0) const;

 
     /**
         Deletes the specified directory from the file system.
 
     /**
         Deletes the specified directory from the file system.

+
+        @param dir
+            The directory to delete
+        @param flags
+            Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
+            default contains neither so the directory will not be removed
+            unless it is empty.
+
+        @return Returns @true if the directory was successfully deleted, @false
+                otherwise.

     */
     */

-    static bool Rmdir(const wxString& dir);
+    static bool Rmdir(const wxString& dir, int flags = 0);

 
     /**
         Compares the filename using the rules of this platform.
 
     /**
         Compares the filename using the rules of this platform.


@@ -943,7 +1083,7 @@ public:
     /**
         Changes the current working directory.
     */
     /**
         Changes the current working directory.
     */

-    bool SetCwd();
+    bool SetCwd() const;

 
     /**
         Changes the current working directory.
 
     /**
         Changes the current working directory.


@@ -982,13 +1122,23 @@ public:
     */
     void SetName(const wxString& name);
 
     */
     void SetName(const wxString& name);
 

+    /**
+        Sets the full path.
+
+        The @a path argument includes both the path (and the volume, if
+        supported by @a format) and the name and extension.
+
+        @see GetPath()
+     */
+    void SetPath(const wxString& path, wxPathFormat format = wxPATH_NATIVE);
+

     /**
         Sets the file creation and last access/modification times (any of the pointers
         may be @NULL).
     */
     bool SetTimes(const wxDateTime* dtAccess,
                   const wxDateTime* dtMod,
     /**
         Sets the file creation and last access/modification times (any of the pointers
         may be @NULL).
     */
     bool SetTimes(const wxDateTime* dtAccess,
                   const wxDateTime* dtMod,

-                  const wxDateTime* dtCreate);
+                  const wxDateTime* dtCreate) const;

 
     /**
         Sets the volume specifier.
 
     /**
         Sets the volume specifier.


@@ -1014,18 +1164,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.
     */
         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,
                           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);
     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,
     static void SplitPath(const wxString& fullpath,
                           wxString* path,
                           wxString* name,


@@ -1044,10 +1195,32 @@ public:
                             wxString* path,
                             wxPathFormat format = wxPATH_NATIVE);
 
                             wxString* path,
                             wxPathFormat format = wxPATH_NATIVE);
 

+
+    /**
+        Strip the file extension.
+
+        This function does more than just removing everything after the last
+        period from the string, for example it will return the string ".vimrc"
+        unchanged because the part after the period is not an extension but the
+        file name in this case. You can use wxString::BeforeLast() to really
+        get just the part before the last period (but notice that that function
+        returns empty string if period is not present at all unlike this
+        function which returns the @a fullname unchanged in this case).
+
+        @param fullname
+           File path including name and, optionally, extension.
+
+        @return
+            File path without extension
+
+        @since 2.9.0
+    */
+    static wxString StripExtension(const wxString& fullname);
+

     /**
         Sets the access and modification times to the current moment.
     */
     /**
         Sets the access and modification times to the current moment.
     */

-    bool Touch();
+    bool Touch() const;

 
     /**
         Returns @true if the filenames are different. The string @e filenames
 
     /**
         Returns @true if the filenames are different. The string @e filenames


@@ -1083,4 +1256,3 @@ public:
     */
     wxFileName& operator=(const wxString& filename);
 };
     */
     wxFileName& operator=(const wxString& filename);
 };

-