X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/395f3aa8bdd6b9844d59ba159b597cef61638caf..ea160f01c60cfc879e1ba3ffec76d113a0404603:/interface/wx/filename.h diff --git a/interface/wx/filename.h b/interface/wx/filename.h index 774c6b76df..29f79a94f6 100644 --- a/interface/wx/filename.h +++ b/interface/wx/filename.h @@ -3,7 +3,7 @@ // 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 }; +/** + 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 @@ -42,7 +61,7 @@ enum wxPathNormalize //! 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_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. @@ -53,6 +72,48 @@ enum wxPathNormalize 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 +}; + +/** + Flags for wxFileName::Exists(). + + @since 2.9.5 + */ +enum +{ + wxFILE_EXISTS_REGULAR = 0x0001, //!< Check for existence of a regular file + wxFILE_EXISTS_DIR = 0x0002, //!< Check for existence of a directory + /** + Check for existence of a symlink. + + Notice that this flag also sets ::wxFILE_EXISTS_NO_FOLLOW, otherwise it + would never be satisfied as wxFileName::Exists() would be checking for + the existence of the symlink target and not the symlink itself. + */ + wxFILE_EXISTS_SYMLINK = 0x1004, + wxFILE_EXISTS_DEVICE = 0x0008, //!< Check for existence of a device + wxFILE_EXISTS_FIFO = 0x0016, //!< Check for existence of a FIFO + wxFILE_EXISTS_SOCKET = 0x0032, //!< Check for existence of a socket + wxFILE_EXISTS_NO_FOLLOW = 0x1000 //!< Don't dereference a contained symbolic link + wxFILE_EXISTS_ANY = 0x1FFF, //!< Check for existence of anything +}; + /** The return value of wxFileName::GetSize() in case of error. */ @@ -92,7 +153,7 @@ wxULongLong wxInvalidSize; wxFileName::IsDirReadable() use wxFileName::GetPath() whereas methods dealing with file names like wxFileName::IsFileReadable() use wxFileName::GetFullPath(). - If it is not known wether a string contains a directory name or a complete + If it is not known whether a string contains a directory name or a complete file name (such as when interpreting user input) you need to use the static function wxFileName::DirExists() (or its identical variants wxDir::Exists() and wxDirExists()) and construct the wxFileName instance accordingly. @@ -276,12 +337,17 @@ public: wxPathFormat format = wxPATH_NATIVE); /** - Appends a directory component to the path. This component should contain a - single directory name level, i.e. not contain any path or volume separators nor - should it be empty, otherwise the function does nothing (and generates an - assert failure in debug build). + Appends a directory component to the path. + + This component should contain a single directory name level, i.e. not + contain any path or volume separators nor should it be empty, otherwise + the function does nothing and returns false (and generates an assert + failure in debug build). + + Notice that the return value is only available in wxWidgets 2.9.5 or + later. */ - void AppendDir(const wxString& dir); + bool AppendDir(const wxString& dir); /** Creates the file name from another filename object. @@ -295,7 +361,7 @@ public: wxPathFormat format = wxPATH_NATIVE); /** - Creates the file name from volumne, path, name and extension. + Creates the file name from volume, path, name and extension. */ void Assign(const wxString& volume, const wxString& path, const wxString& name, @@ -304,7 +370,7 @@ public: wxPathFormat format = wxPATH_NATIVE); /** - Creates the file name from volumne, path, name and extension. + Creates the file name from volume, path, name and extension. */ void Assign(const wxString& volume, const wxString& path, const wxString& name, @@ -330,7 +396,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. @@ -384,38 +450,59 @@ 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 - directory, otherwise it is created in the default system directory for the - temporary files or in the current directory. + If @a prefix is an absolute path and ends in a separator, the + temporary file is created in this directory; if it is an absolute + filepath or there is no separator, the temporary file is created in its + path, with the 'name' segment prepended to the temporary filename; + otherwise it is created in the default system directory for temporary + files or in the current directory. If the function succeeds, the temporary file is actually created. - If @a fileTemp is not @NULL, this file will be opened using the name of - the temporary file. When possible, this is done in an atomic way ensuring that - no race condition occurs between the temporary file name generation and opening - it which could often lead to security compromise on the multiuser systems. - If @a fileTemp is @NULL, the file is only created, but not opened. + If @a fileTemp is not @NULL, this wxFile will be opened using the name of + the temporary file. Where possible this is done in an atomic way to ensure that + no race condition occurs between creating the temporary file name and opening + it, which might lead to a security compromise on multiuser systems. + If @a fileTemp is @NULL, the file is created but not opened. Under Unix, the temporary file will have read and write permissions for the - owner only to minimize the security problems. + owner only, to minimize security problems. @param prefix - Prefix to use for the temporary file name construction + Location to use for the temporary file name construction. If @a prefix + is a directory it must have a terminal separator @param fileTemp - The file to open or @NULL to just get the name + The file to open, or @NULL just to get the name - @return The full temporary file name or an empty string on error. + @return The full temporary filepath, or an empty string on error. */ static wxString CreateTempFileName(const wxString& prefix, wxFile* fileTemp = NULL); + /** + This is the same as CreateTempFileName(const wxString &prefix, wxFile *fileTemp) + but takes a wxFFile parameter instead of wxFile. + */ + static wxString CreateTempFileName(const wxString& prefix, + wxFFile* fileTemp = NULL); + + /** Returns @true if the directory with this name exists. + + Notice that this function tests the directory part of this object, + i.e. the string returned by GetPath(), and not the full path returned + by GetFullPath(). + + @see FileExists(), Exists() */ bool DirExists() const; /** - Returns @true if the directory with this name exists. + Returns @true if the directory with name @a dir exists. + + @see FileExists(), Exists() */ static bool DirExists(const wxString& dir); @@ -426,17 +513,69 @@ public: static wxFileName DirName(const wxString& dir, wxPathFormat format = wxPATH_NATIVE); + /** + Turns off symlink dereferencing. + + By default, all operations in this class work on the target of a + symbolic link (symlink) if the path of the file is actually a symlink. + Using this method allows to turn off this "symlink following" behaviour + and apply the operations to this path itself, even if it is a symlink. + + The following methods are currently affected by this option: + - GetTimes() (but not SetTimes() as there is no portable way to + change the time of symlink itself). + - Existence checks: FileExists(), DirExists() and Exists() (notice + that static versions of these methods always follow symlinks). + - IsSameAs(). + + @see ShouldFollowLink() + + @since 2.9.5 + */ + void DontFollowLink(); + + /** + Calls the static overload of this function with the full path of this + object. + + @since 2.9.4 (@a flags is new since 2.9.5) + */ + bool Exists(int flags = wxFILE_EXISTS_ANY) const; + + /** + Returns @true if either a file or a directory or something else with + this name exists in the file system. + + Don't dereference @a path if it is a symbolic link and @a flags + argument contains ::wxFILE_EXISTS_NO_FOLLOW. + + This method is equivalent to @code FileExists() || DirExists() @endcode + under Windows, but under Unix it also returns true if the file + identifies a special file system object such as a device, a socket or a + FIFO. + + Alternatively you may check for the existence of a file system entry of + a specific type by passing the appropriate @a flags (this parameter is + new since wxWidgets 2.9.5). E.g. to test for a symbolic link existence + you could use ::wxFILE_EXISTS_SYMLINK. + + @since 2.9.4 + + @see FileExists(), DirExists() + */ + static bool Exists(const wxString& path, int flags = wxFILE_EXISTS_ANY); + /** Returns @true if the file with this name exists. - @see DirExists() + @see DirExists(), Exists() */ 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(), Exists() */ static bool FileExists(const wxString& file); @@ -500,30 +639,41 @@ public: */ 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 for bytes, + kibibytes, mebibytes, 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). @@ -559,6 +709,10 @@ public: Don't include the trailing separator in the returned string. This is the default (the value of this flag is 0) and exists only for symmetry with wxPATH_GET_SEPARATOR. + + @note If the path is a toplevel one (e.g. @c "/" on Unix or @c "C:\" on + Windows), then the returned path will contain trailing separator + even with @c wxPATH_NO_SEPARATOR. */ wxString GetPath(int flags = wxPATH_GET_VOLUME, wxPathFormat format = wxPATH_NATIVE) const; @@ -617,7 +771,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. @@ -692,10 +846,16 @@ public: bool HasVolume() const; /** - Inserts a directory component before the zero-based position in the directory - list. Please see AppendDir() for important notes. + Inserts a directory component before the zero-based position in the + directory list. + + As with AppendDir(), @a dir must be a single directory name and the + function returns @false and does nothing else if it isn't. + + Notice that the return value is only available in wxWidgets 2.9.5 or + later. */ - void InsertDir(size_t before, const wxString& dir); + bool InsertDir(size_t before, const wxString& dir); /** Returns @true if this filename is absolute. @@ -797,6 +957,24 @@ public: 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. */ @@ -804,6 +982,8 @@ public: /** On Mac OS, gets the common type and creator for the given extension. + + @onlyfor{wxosx} */ static bool MacFindDefaultTypeAndCreator(const wxString& ext, wxUint32* type, @@ -812,6 +992,8 @@ public: /** On Mac OS, registers application defined extensions and their default type and creator. + + @onlyfor{wxosx} */ static void MacRegisterDefaultTypeAndCreator(const wxString& ext, wxUint32 type, @@ -820,6 +1002,8 @@ public: /** On Mac OS, looks up the appropriate type and creator from the registration and then sets it. + + @onlyfor{wxosx} */ bool MacSetDefaultTypeAndCreator(); @@ -870,7 +1054,7 @@ public: @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. @@ -892,9 +1076,16 @@ public: int flags = 0); /** - Normalize the path. With the default flags value, the path will be - made absolute, without any ".." and "." and all environment - variables will be expanded in it. + Normalize the path. + + With the default flags value, the path will be made absolute, without + any ".." and "." and all environment variables will be expanded in it. + + Notice that in some rare cases normalizing a valid path may result in + an invalid wxFileName object. E.g. normalizing "./" path using + wxPATH_NORM_DOTS but not wxPATH_NORM_ABSOLUTE will result in a + completely empty and thus invalid object. As long as there is a non + empty file name the result of normalization will be valid however. @param flags The kind of normalization to do with the file name. It can be @@ -978,13 +1169,31 @@ public: /** 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. + + @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. @@ -995,7 +1204,7 @@ public: /** Changes the current working directory. */ - bool SetCwd(); + bool SetCwd() const; /** Changes the current working directory. @@ -1034,19 +1243,48 @@ public: */ void SetName(const wxString& name); + /** + Sets the path. + + The @a path argument includes both the path and the volume, if + supported by @a format. + + Calling this function doesn't affect the name and extension components, + to change them as well you can use Assign() or just an assignment + operator. + + @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). + + Notice that the file creation time can't be changed under Unix, so @a + dtCreate is ignored there (but @true is still returned). Under Windows + all three times can be set. */ bool SetTimes(const wxDateTime* dtAccess, const wxDateTime* dtMod, - const wxDateTime* dtCreate); + const wxDateTime* dtCreate) const; /** Sets the volume specifier. */ void SetVolume(const wxString& volume); + /** + Return whether some operations will follow symlink. + + By default, file operations "follow symlink", i.e. operate on its + target and not on the symlink itself. See DontFollowLink() for more + information. + + @since 2.9.5 + */ + bool ShouldFollowLink() const; + //@{ /** This function splits a full file name into components: the volume (with the @@ -1066,18 +1304,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, @@ -1096,10 +1335,32 @@ public: 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. */ - bool Touch(); + bool Touch() const; /** Returns @true if the filenames are different. The string @e filenames @@ -1135,4 +1396,3 @@ public: */ wxFileName& operator=(const wxString& filename); }; -