1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: filename.h 3 // Purpose: interface of wxFileName 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 9 /** 10 The various values for the path format: this mainly affects the path 11 separator but also whether or not the path has the drive part 12 (as under Windows). 13 14 See wxFileName for more info. 15 */ 16 enum wxPathFormat 17 { 18 wxPATH_NATIVE = 0, //!< the path format for the current platform. 19 wxPATH_UNIX, 20 wxPATH_BEOS = wxPATH_UNIX, 21 wxPATH_MAC, 22 wxPATH_DOS, 23 wxPATH_WIN = wxPATH_DOS, 24 wxPATH_OS2 = wxPATH_DOS, 25 wxPATH_VMS, 26 27 wxPATH_MAX //!< Not a valid value for specifying path format 28 }; 29 30 /** 31 Different conventions for human readable sizes. 32 33 @see wxFileName::GetHumanReadableSize(). 34 35 @since 2.9.1 36 */ 37 enum wxSizeConvention 38 { 39 /// 1024 bytes = 1KB. 40 wxSIZE_CONV_TRADITIONAL, 41 42 /// 1024 bytes = 1KiB. 43 wxSIZE_CONV_IEC, 44 45 /// 1000 bytes = 1KB. 46 wxSIZE_CONV_SI 47 }; 48 49 50 /** 51 The kind of normalization to do with the file name: these values can be 52 or'd together to perform several operations at once. 53 See wxFileName::Normalize() for more info. 54 */ 55 enum wxPathNormalize 56 { 57 //! Replace environment variables with their values. 58 //! wxFileName understands both Unix and Windows (but only under Windows) environment 59 //! variables expansion: i.e. @c "$var", @c "$(var)" and @c "${var}" are always understood 60 //! and in addition under Windows @c "%var%" is also. 61 wxPATH_NORM_ENV_VARS = 0x0001, 62 63 wxPATH_NORM_DOTS = 0x0002, //!< Squeeze all @c ".." and @c ".". 64 wxPATH_NORM_TILDE = 0x0004, //!< Replace @c "~" and @c "~user" (Unix only). 65 wxPATH_NORM_CASE = 0x0008, //!< If the platform is case insensitive, make lowercase the path. 66 wxPATH_NORM_ABSOLUTE = 0x0010, //!< Make the path absolute. 67 wxPATH_NORM_LONG = 0x0020, //!< Expand the path to the "long" form (Windows only). 68 wxPATH_NORM_SHORTCUT = 0x0040, //!< Resolve the shortcut, if it is a shortcut (Windows only). 69 70 //! A value indicating all normalization flags except for @c wxPATH_NORM_CASE. 71 wxPATH_NORM_ALL = 0x00ff & ~wxPATH_NORM_CASE 72 }; 73 74 /** 75 Flags for wxFileName::Rmdir(). 76 */ 77 enum 78 { 79 /// Delete the specified directory and its subdirectories if they are empty. 80 wxPATH_RMDIR_FULL = 1, 81 82 /** 83 Delete the specified directory and all the files and subdirectories in it 84 recursively. 85 86 This flag is obviously @b dangerous and should be used with care and 87 after asking the user for confirmation. 88 */ 89 wxPATH_RMDIR_RECURSIVE = 2 90 }; 91 92 /** 93 Flags for wxFileName::Exists(). 94 95 @since 2.9.5 96 */ 97 enum 98 { 99 wxFILE_EXISTS_REGULAR = 0x0001, //!< Check for existence of a regular file 100 wxFILE_EXISTS_DIR = 0x0002, //!< Check for existence of a directory 101 /** 102 Check for existence of a symlink. 103 104 Notice that this flag also sets ::wxFILE_EXISTS_NO_FOLLOW, otherwise it 105 would never be satisfied as wxFileName::Exists() would be checking for 106 the existence of the symlink target and not the symlink itself. 107 */ 108 wxFILE_EXISTS_SYMLINK = 0x1004, 109 wxFILE_EXISTS_DEVICE = 0x0008, //!< Check for existence of a device 110 wxFILE_EXISTS_FIFO = 0x0016, //!< Check for existence of a FIFO 111 wxFILE_EXISTS_SOCKET = 0x0032, //!< Check for existence of a socket 112 wxFILE_EXISTS_NO_FOLLOW = 0x1000 //!< Don't dereference a contained symbolic link 113 wxFILE_EXISTS_ANY = 0x1FFF, //!< Check for existence of anything 114 }; 115 116 /** 117 The return value of wxFileName::GetSize() in case of error. 118 */ 119 wxULongLong wxInvalidSize; 120 121 122 /** 123 @class wxFileName 124 125 wxFileName encapsulates a file name. 126 127 This class serves two purposes: first, it provides the functions to split the 128 file names into components and to recombine these components in the full file 129 name which can then be passed to the OS file functions 130 (and @ref group_funcmacro_file "wxWidgets functions" wrapping them). 131 Second, it includes the functions for working with the files itself. Note that 132 to change the file data you should use wxFile class instead. 133 wxFileName provides functions for working with the file attributes. 134 135 When working with directory names (i.e. without filename and extension) 136 make sure not to misuse the file name part of this class with the last 137 directory. Instead initialize the wxFileName instance like this: 138 139 @code 140 wxFileName dirname( "C:\mydir", "" ); 141 MyMethod( dirname.GetPath() ); 142 @endcode 143 144 The same can be done using the static method wxFileName::DirName(): 145 146 @code 147 wxFileName dirname = wxFileName::DirName( "C:\mydir" ); 148 MyMethod( dirname.GetPath() ); 149 @endcode 150 151 Accordingly, methods dealing with directories or directory names like 152 wxFileName::IsDirReadable() use wxFileName::GetPath() whereas methods dealing 153 with file names like wxFileName::IsFileReadable() use wxFileName::GetFullPath(). 154 155 If it is not known whether a string contains a directory name or a complete 156 file name (such as when interpreting user input) you need to use the static 157 function wxFileName::DirExists() (or its identical variants wxDir::Exists() and 158 wxDirExists()) and construct the wxFileName instance accordingly. 159 This will only work if the directory actually exists, of course: 160 161 @code 162 wxString user_input; 163 // get input from user 164 165 wxFileName fname; 166 if (wxDirExists(user_input)) 167 fname.AssignDir( user_input ); 168 else 169 fname.Assign( user_input ); 170 @endcode 171 172 Please note that many wxFileName methods accept the path format argument 173 which is by @c wxPATH_NATIVE by default meaning to use the path format 174 native for the current platform. 175 The path format affects the operation of wxFileName functions in several ways: 176 first and foremost, it defines the path separator character to use, but it 177 also affects other things such as whether the path has the drive part or not. 178 See wxPathFormat for more info. 179 180 181 @section filename_format File name format 182 183 wxFileName currently supports the file names in the Unix, DOS/Windows, 184 Mac OS and VMS formats. Although these formats are quite different, 185 wxFileName tries to treat them all in the same generic way. 186 It supposes that all file names consist of the following parts: the volume 187 (also known as drive under Windows or device under VMS), the path which is 188 a sequence of directory names separated by the path separators and the full 189 filename itself which, in turn, is composed from the base file name and the 190 extension. All of the individual components of the file name may be empty 191 and, for example, the volume name is always empty under Unix, but if they 192 are all empty simultaneously, the filename object is considered to be in an 193 invalid state and wxFileName::IsOk() returns false for it. 194 195 File names can be case-sensitive or not, the function wxFileName::IsCaseSensitive() 196 allows determining this. The rules for determining whether the file name is 197 absolute or relative also depend on the file name format and the only portable way 198 to answer this question is to use wxFileName::IsAbsolute() or wxFileName::IsRelative() 199 method. 200 201 Note that on Windows,"X:" refers to the current working directory on drive X. 202 Therefore, a wxFileName instance constructed from for example "X:dir/file.ext" 203 treats the portion beyond drive separator as being relative to that directory. 204 To ensure that the filename is absolute, you may use wxFileName::MakeAbsolute(). 205 There is also an inverse function wxFileName::MakeRelativeTo() which undoes 206 what wxFileName::Normalize(wxPATH_NORM_DOTS) does. 207 Other functions returning information about the file format provided by this 208 class are wxFileName::GetVolumeSeparator(), wxFileName::IsPathSeparator(). 209 210 211 @section filename_construction File name construction 212 213 You can initialize a wxFileName instance using one of the following functions: 214 215 @li wxFileName::wxFileName() 216 @li wxFileName::Assign() 217 @li wxFileName::AssignCwd() 218 @li wxFileName::AssignDir() 219 @li wxFileName::AssignHomeDir() 220 @li wxFileName::AssignTempFileName() 221 @li wxFileName::DirName() 222 @li wxFileName::FileName() 223 @li wxFileName::operator=() 224 225 226 @section filename_tests File name tests 227 228 Before doing other tests, you should use wxFileName::IsOk() to verify that 229 the filename is well defined. If it is, FileExists() can be used to test whether 230 a file with such name exists and wxFileName::DirExists() can be used to test 231 for directory existence. 232 File names should be compared using the wxFileName::SameAs() method or 233 wxFileName::operator==(). For testing basic access modes, you can use: 234 235 @li wxFileName::IsDirWritable() 236 @li wxFileName::IsDirReadable() 237 @li wxFileName::IsFileWritable() 238 @li wxFileName::IsFileReadable() 239 @li wxFileName::IsFileExecutable() 240 241 242 @section filename_components File name components 243 244 These functions allow to examine and modify the individual directories 245 of the path: 246 247 @li wxFileName::AppendDir() 248 @li wxFileName::InsertDir() 249 @li wxFileName::GetDirCount() 250 @li wxFileName::PrependDir() 251 @li wxFileName::RemoveDir() 252 @li wxFileName::RemoveLastDir() 253 254 To change the components of the file name individually you can use the 255 following functions: 256 257 @li wxFileName::GetExt() 258 @li wxFileName::GetName() 259 @li wxFileName::GetVolume() 260 @li wxFileName::HasExt() 261 @li wxFileName::HasName() 262 @li wxFileName::HasVolume() 263 @li wxFileName::SetExt() 264 @li wxFileName::ClearExt() 265 @li wxFileName::SetEmptyExt() 266 @li wxFileName::SetName() 267 @li wxFileName::SetVolume() 268 269 270 @section filename_operations File name operations 271 272 These methods allow to work with the file creation, access and modification 273 times. Note that not all filesystems under all platforms implement these times 274 in the same way. For example, the access time under Windows has a resolution of 275 one day (so it is really the access date and not time). The access time may be 276 updated when the file is executed or not depending on the platform. 277 278 @li wxFileName::GetModificationTime() 279 @li wxFileName::GetTimes() 280 @li wxFileName::SetTimes() 281 @li wxFileName::Touch() 282 283 Other file system operations functions are: 284 285 @li wxFileName::Mkdir() 286 @li wxFileName::Rmdir() 287 288 @section symlink_behavior Behavior with symlinks 289 290 wxFileName instances can store the path to symlinks on systems that support them. 291 When the path is for a symlink, the behavior of the following methods can be modified 292 to either operate on the symlink itself or on the file the link points to. 293 294 @li wxFileName::FileExists() 295 @li wxFileName::DirExists() 296 @li wxFileName::Exists() 297 @li wxFileName::SameAs() 298 @li wxFileName::GetTimes() 299 300 By default, those functions will operate on the target of the link, but they can be 301 made to operate on the link itself by calling wxFileName::DontFollowLink(). The current 302 link-following mode can be examined by calling wxFileName::ShouldFollowLink(). 303 304 The wxFileName::ResolveLink() method can be used to get the absolute path for the target 305 of the symlink. 306 307 @library{wxbase} 308 @category{file} 309 */ 310 class wxFileName 311 { 312 public: 313 /** 314 Default constructor. 315 */ 316 wxFileName(); 317 318 /** 319 Copy constructor. 320 */ 321 wxFileName(const wxFileName& filename); 322 323 /** 324 Constructor taking a full filename. 325 326 If it terminates with a '/', a directory path is constructed 327 (the name will be empty), otherwise a file name and extension 328 are extracted from it. 329 */ 330 wxFileName(const wxString& fullpath, 331 wxPathFormat format = wxPATH_NATIVE); 332 333 /** 334 Constructor a directory name and file name. 335 */ 336 wxFileName(const wxString& path, const wxString& name, 337 wxPathFormat format = wxPATH_NATIVE); 338 339 /** 340 Constructor from a directory name, base file name and extension. 341 */ 342 wxFileName(const wxString& path, const wxString& name, 343 const wxString& ext, 344 wxPathFormat format = wxPATH_NATIVE); 345 346 /** 347 Constructor from a volume name, a directory name, base file name and extension. 348 */ 349 wxFileName(const wxString& volume, const wxString& path, 350 const wxString& name, 351 const wxString& ext, 352 wxPathFormat format = wxPATH_NATIVE); 353 354 /** 355 Appends a directory component to the path. 356 357 This component should contain a single directory name level, i.e. not 358 contain any path or volume separators nor should it be empty, otherwise 359 the function does nothing and returns false (and generates an assert 360 failure in debug build). 361 362 Notice that the return value is only available in wxWidgets 2.9.5 or 363 later. 364 */ 365 bool AppendDir(const wxString& dir); 366 367 /** 368 Creates the file name from another filename object. 369 */ 370 void Assign(const wxFileName& filepath); 371 372 /** 373 Creates the file name from a full file name with a path. 374 */ 375 void Assign(const wxString& fullpath, 376 wxPathFormat format = wxPATH_NATIVE); 377 378 /** 379 Creates the file name from volume, path, name and extension. 380 */ 381 void Assign(const wxString& volume, const wxString& path, 382 const wxString& name, 383 const wxString& ext, 384 bool hasExt, 385 wxPathFormat format = wxPATH_NATIVE); 386 387 /** 388 Creates the file name from volume, path, name and extension. 389 */ 390 void Assign(const wxString& volume, const wxString& path, 391 const wxString& name, 392 const wxString& ext, 393 wxPathFormat format = wxPATH_NATIVE); 394 395 /** 396 Creates the file name from file path and file name. 397 */ 398 void Assign(const wxString& path, const wxString& name, 399 wxPathFormat format = wxPATH_NATIVE); 400 401 /** 402 Creates the file name from path, name and extension. 403 */ 404 void Assign(const wxString& path, const wxString& name, 405 const wxString& ext, 406 wxPathFormat format = wxPATH_NATIVE); 407 408 /** 409 Makes this object refer to the current working directory on the specified 410 volume (or current volume if @a volume is empty). 411 412 @see GetCwd() 413 */ 414 void AssignCwd(const wxString& volume = wxEmptyString); 415 416 /** 417 Sets this file name object to the given directory name. 418 The name and extension will be empty. 419 */ 420 void AssignDir(const wxString& dir, 421 wxPathFormat format = wxPATH_NATIVE); 422 423 /** 424 Sets this file name object to the home directory. 425 */ 426 void AssignHomeDir(); 427 428 /** 429 The function calls CreateTempFileName() to create a temporary file 430 and sets this object to the name of the file. 431 432 If a temporary file couldn't be created, the object is put into 433 an invalid state (see IsOk()). 434 */ 435 void AssignTempFileName(const wxString& prefix); 436 437 /** 438 The function calls CreateTempFileName() to create a temporary 439 file name and open @a fileTemp with it. 440 441 If the file couldn't be opened, the object is put into 442 an invalid state (see IsOk()). 443 */ 444 void AssignTempFileName(const wxString& prefix, wxFile* fileTemp); 445 446 /** 447 The function calls CreateTempFileName() to create a temporary 448 file name and open @a fileTemp with it. 449 450 If the file couldn't be opened, the object is put into 451 an invalid state (see IsOk()). 452 */ 453 void AssignTempFileName(const wxString& prefix, wxFFile* fileTemp); 454 455 /** 456 Reset all components to default, uninitialized state. 457 */ 458 void Clear(); 459 460 /** 461 Removes the extension from the file name resulting in a 462 file name with no trailing dot. 463 464 @see SetExt(), SetEmptyExt() 465 */ 466 void ClearExt(); 467 468 469 /** 470 Returns a temporary file name starting with the given @e prefix. 471 If @a prefix is an absolute path and ends in a separator, the 472 temporary file is created in this directory; if it is an absolute 473 filepath or there is no separator, the temporary file is created in its 474 path, with the 'name' segment prepended to the temporary filename; 475 otherwise it is created in the default system directory for temporary 476 files or in the current directory. 477 478 If the function succeeds, the temporary file is actually created. 479 If @a fileTemp is not @NULL, this wxFile will be opened using the name of 480 the temporary file. Where possible this is done in an atomic way to ensure that 481 no race condition occurs between creating the temporary file name and opening 482 it, which might lead to a security compromise on multiuser systems. 483 If @a fileTemp is @NULL, the file is created but not opened. 484 Under Unix, the temporary file will have read and write permissions for the 485 owner only, to minimize security problems. 486 487 @param prefix 488 Location to use for the temporary file name construction. If @a prefix 489 is a directory it must have a terminal separator 490 @param fileTemp 491 The file to open, or @NULL just to get the name 492 493 @return The full temporary filepath, or an empty string on error. 494 */ 495 static wxString CreateTempFileName(const wxString& prefix, 496 wxFile* fileTemp = NULL); 497 498 /** 499 This is the same as CreateTempFileName(const wxString &prefix, wxFile *fileTemp) 500 but takes a wxFFile parameter instead of wxFile. 501 */ 502 static wxString CreateTempFileName(const wxString& prefix, 503 wxFFile* fileTemp = NULL); 504 505 506 /** 507 Returns @true if the directory with this name exists. 508 509 Notice that this function tests the directory part of this object, 510 i.e. the string returned by GetPath(), and not the full path returned 511 by GetFullPath(). 512 513 @see FileExists(), Exists() 514 */ 515 bool DirExists() const; 516 517 /** 518 Returns @true if the directory with name @a dir exists. 519 520 @see FileExists(), Exists() 521 */ 522 static bool DirExists(const wxString& dir); 523 524 /** 525 Returns the object corresponding to the directory with the given name. 526 The @a dir parameter may have trailing path separator or not. 527 */ 528 static wxFileName DirName(const wxString& dir, 529 wxPathFormat format = wxPATH_NATIVE); 530 531 /** 532 Turns off symlink dereferencing. 533 534 By default, all operations in this class work on the target of a 535 symbolic link (symlink) if the path of the file is actually a symlink. 536 Using this method allows turning off this "symlink following" behaviour 537 and apply the operations to this path itself, even if it is a symlink. 538 539 The following methods are currently affected by this option: 540 - GetTimes() (but not SetTimes() as there is no portable way to 541 change the time of symlink itself). 542 - Existence checks: FileExists(), DirExists() and Exists() (notice 543 that static versions of these methods always follow symlinks). 544 - IsSameAs(). 545 546 @see ShouldFollowLink() 547 548 @since 2.9.5 549 */ 550 void DontFollowLink(); 551 552 /** 553 Calls the static overload of this function with the full path of this 554 object. 555 556 @since 2.9.4 (@a flags is new since 2.9.5) 557 */ 558 bool Exists(int flags = wxFILE_EXISTS_ANY) const; 559 560 /** 561 Returns @true if either a file or a directory or something else with 562 this name exists in the file system. 563 564 Don't dereference @a path if it is a symbolic link and @a flags 565 argument contains ::wxFILE_EXISTS_NO_FOLLOW. 566 567 This method is equivalent to @code FileExists() || DirExists() @endcode 568 under Windows, but under Unix it also returns true if the file 569 identifies a special file system object such as a device, a socket or a 570 FIFO. 571 572 Alternatively you may check for the existence of a file system entry of 573 a specific type by passing the appropriate @a flags (this parameter is 574 new since wxWidgets 2.9.5). E.g. to test for a symbolic link existence 575 you could use ::wxFILE_EXISTS_SYMLINK. 576 577 @since 2.9.4 578 579 @see FileExists(), DirExists() 580 */ 581 static bool Exists(const wxString& path, int flags = wxFILE_EXISTS_ANY); 582 583 /** 584 Returns @true if the file with this name exists. 585 586 @see DirExists(), Exists() 587 */ 588 bool FileExists() const; 589 590 /** 591 Returns @true if the file with name @a file exists. 592 593 @see DirExists(), Exists() 594 */ 595 static bool FileExists(const wxString& file); 596 597 /** 598 Returns the file name object corresponding to the given @e file. This 599 function exists mainly for symmetry with DirName(). 600 */ 601 static wxFileName FileName(const wxString& file, 602 wxPathFormat format = wxPATH_NATIVE); 603 604 /** 605 Retrieves the value of the current working directory on the specified volume. 606 If the volume is empty, the program's current working directory is returned for 607 the current volume. 608 609 @return The string containing the current working directory or an empty 610 string on error. 611 612 @see AssignCwd() 613 */ 614 static wxString GetCwd(const wxString& volume = wxEmptyString); 615 616 /** 617 Returns the number of directories in the file name. 618 */ 619 size_t GetDirCount() const; 620 621 /** 622 Returns the directories in string array form. 623 */ 624 const wxArrayString& GetDirs() const; 625 626 /** 627 Returns the file name extension. 628 */ 629 wxString GetExt() const; 630 631 /** 632 Returns the characters that can't be used in filenames and directory names 633 for the specified format. 634 */ 635 static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); 636 637 /** 638 Returns the canonical path format for this platform. 639 */ 640 static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE); 641 642 /** 643 Returns the full name (including extension but excluding directories). 644 */ 645 wxString GetFullName() const; 646 647 /** 648 Returns the full path with name and extension. 649 */ 650 wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE) const; 651 652 /** 653 Returns the home directory. 654 */ 655 static wxString GetHomeDir(); 656 657 //@{ 658 /** 659 Returns the representation of the file size in a human-readable form. 660 661 In the first version, the size of this file is used. In the second one, 662 the specified size @a bytes is used. 663 664 If the file size could not be retrieved or @a bytes is ::wxInvalidSize 665 or zero, the @c failmsg string is returned. 666 667 Otherwise the returned string is a floating-point number with @c 668 precision decimal digits followed by the abbreviation of the unit used. 669 By default the traditional, although incorrect, convention of using SI 670 units for multiples of 1024 is used, i.e. returned string will use 671 suffixes of B, KB, MB, GB, TB for bytes, kilobytes, megabytes, 672 gigabytes and terabytes respectively. With the IEC convention the names 673 of the units are changed to B, KiB, MiB, GiB and TiB for bytes, 674 kibibytes, mebibytes, gibibytes and tebibytes. Finally, with SI 675 convention the same B, KB, MB, GB and TB suffixes are used but in their 676 correct SI meaning, i.e. as multiples of 1000 and not 1024. 677 678 Support for the different size conventions is new in wxWidgets 2.9.1, 679 in previous versions only the traditional convention was implemented. 680 */ 681 wxString 682 GetHumanReadableSize(const wxString& failmsg = _("Not available"), 683 int precision = 1, 684 wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL) const; 685 686 static wxString 687 GetHumanReadableSize(const wxULongLong& bytes, 688 const wxString& nullsize = _("Not available"), 689 int precision = 1, 690 wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL); 691 //@} 692 693 /** 694 Return the long form of the path (returns identity on non-Windows platforms). 695 */ 696 wxString GetLongPath() const; 697 698 /** 699 Returns the last time the file was last modified. 700 */ 701 wxDateTime GetModificationTime() const; 702 703 /** 704 Returns the name part of the filename (without extension). 705 706 @see GetFullName() 707 */ 708 wxString GetName() const; 709 710 /** 711 Returns the path part of the filename (without the name or extension). 712 713 The possible flags values are: 714 715 - @b wxPATH_GET_VOLUME: 716 Return the path with the volume (does nothing for the filename formats 717 without volumes), otherwise the path without volume part is returned. 718 719 - @b wxPATH_GET_SEPARATOR: 720 Return the path with the trailing separator, if this flag is not given 721 there will be no separator at the end of the path. 722 723 - @b wxPATH_NO_SEPARATOR: 724 Don't include the trailing separator in the returned string. This is 725 the default (the value of this flag is 0) and exists only for symmetry 726 with wxPATH_GET_SEPARATOR. 727 728 @note If the path is a toplevel one (e.g. @c "/" on Unix or @c "C:\" on 729 Windows), then the returned path will contain trailing separator 730 even with @c wxPATH_NO_SEPARATOR. 731 */ 732 wxString GetPath(int flags = wxPATH_GET_VOLUME, 733 wxPathFormat format = wxPATH_NATIVE) const; 734 735 /** 736 Returns the usually used path separator for this format. 737 For all formats but @c wxPATH_DOS there is only one path separator anyhow, 738 but for DOS there are two of them and the native one, i.e. the backslash 739 is returned by this method. 740 741 @see GetPathSeparators() 742 */ 743 static wxUniChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); 744 745 /** 746 Returns the string containing all the path separators for this format. 747 For all formats but @c wxPATH_DOS this string contains only one character 748 but for DOS and Windows both @c '/' and @c '\' may be used as separators. 749 750 @see GetPathSeparator() 751 */ 752 static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); 753 754 /** 755 Returns the string of characters which may terminate the path part. 756 This is the same as GetPathSeparators() except for VMS 757 path format where ] is used at the end of the path part. 758 */ 759 static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); 760 761 /** 762 Returns the path with the trailing separator, useful for appending the name 763 to the given path. 764 765 This is the same as calling 766 @code 767 GetPath(wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format) 768 @endcode 769 */ 770 wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const; 771 772 /** 773 Return the short form of the path (returns identity on non-Windows platforms). 774 */ 775 wxString GetShortPath() const; 776 777 /** 778 Returns the size of the file If the file does not exist or its size could 779 not be read (because e.g. the file is locked by another process) the returned 780 value is ::wxInvalidSize. 781 */ 782 wxULongLong GetSize() const; 783 784 /** 785 Returns the size of the file If the file does not exist or its size could 786 not be read (because e.g. the file is locked by another process) the returned 787 value is ::wxInvalidSize. 788 */ 789 static wxULongLong GetSize(const wxString& filename); 790 791 /** 792 Returns the directory used for temporary files, for current user. Same as 793 wxStandardPaths::GetTempDir(). 794 */ 795 static wxString GetTempDir(); 796 797 /** 798 Returns the last access, last modification and creation times. 799 The last access time is updated whenever the file is read or written 800 (or executed in the case of Windows), last modification time is only 801 changed when the file is written to. 802 Finally, the creation time is indeed the time when the file was created 803 under Windows and the inode change time under Unix (as it is impossible to 804 retrieve the real file creation time there anyhow) which can also be changed 805 by many operations after the file creation. 806 807 If no filename or extension is specified in this instance of wxFileName 808 (and therefore IsDir() returns @true) then this function will return the 809 directory times of the path specified by GetPath(), otherwise the file 810 times of the file specified by GetFullPath(). 811 Any of the pointers may be @NULL if the corresponding time is not needed. 812 813 @return @true on success, @false if we failed to retrieve the times. 814 */ 815 bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod, 816 wxDateTime* dtCreate) const; 817 818 /** 819 Returns the string containing the volume for this file name, empty if it 820 doesn't have one or if the file system doesn't support volumes at all 821 (for example, Unix). 822 */ 823 wxString GetVolume() const; 824 825 /** 826 Returns the string separating the volume from the path for this format. 827 */ 828 static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); 829 830 /** 831 This function builds a volume path string, for example "C:\\". 832 833 Implemented for the platforms which use drive letters, i.e. MSW only. 834 835 @since 2.9.0 836 837 @param drive 838 The drive letter, 'A' through 'Z' or 'a' through 'z'. 839 840 @param flags 841 @c wxPATH_NO_SEPARATOR or @c wxPATH_GET_SEPARATOR to omit or include 842 the trailing path separator, the default is to include it. 843 844 @return Volume path string. 845 */ 846 static wxString GetVolumeString(char drive, int flags = wxPATH_GET_SEPARATOR); 847 848 /** 849 Returns @true if an extension is present. 850 */ 851 bool HasExt() const; 852 853 /** 854 Returns @true if a name is present. 855 */ 856 bool HasName() const; 857 858 /** 859 Returns @true if a volume specifier is present. 860 */ 861 bool HasVolume() const; 862 863 /** 864 Inserts a directory component before the zero-based position in the 865 directory list. 866 867 As with AppendDir(), @a dir must be a single directory name and the 868 function returns @false and does nothing else if it isn't. 869 870 Notice that the return value is only available in wxWidgets 2.9.5 or 871 later. 872 */ 873 bool InsertDir(size_t before, const wxString& dir); 874 875 /** 876 Returns @true if this filename is absolute. 877 */ 878 bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE) const; 879 880 /** 881 Returns @true if the file names of this type are case-sensitive. 882 */ 883 static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE); 884 885 /** 886 Returns @true if this object represents a directory, @false otherwise 887 (i.e. if it is a file). 888 889 Note that this method doesn't test whether the directory or file really 890 exists, you should use DirExists() or FileExists() for this. 891 */ 892 bool IsDir() const; 893 894 /** 895 Returns @true if the directory component of this instance is an existing 896 directory and this process has read permissions on it. Read permissions 897 on a directory mean that you can list the directory contents but it 898 doesn't imply that you have read permissions on the files contained. 899 */ 900 bool IsDirReadable() const; 901 902 /** 903 Returns @true if the given @e dir is an existing directory and this process 904 has read permissions on it. Read permissions on a directory mean that you 905 can list the directory contents but it doesn't imply that you have read 906 permissions on the files contained. 907 */ 908 static bool IsDirReadable(const wxString& dir); 909 910 /** 911 Returns @true if the directory component of this instance 912 is an existing directory and this process has write permissions on it. 913 Write permissions on a directory mean that you can create new files in the 914 directory. 915 */ 916 bool IsDirWritable() const; 917 918 /** 919 Returns @true if the given @a dir is an existing directory and this 920 process has write permissions on it. 921 Write permissions on a directory mean that you can create new files in the 922 directory. 923 */ 924 static bool IsDirWritable(const wxString& dir); 925 926 /** 927 Returns @true if a file with this name exists and if this process has execute 928 permissions on it. 929 */ 930 bool IsFileExecutable() const; 931 932 /** 933 Returns @true if a file with this name exists and if this process has execute 934 permissions on it. 935 */ 936 static bool IsFileExecutable(const wxString& file); 937 938 /** 939 Returns @true if a file with this name exists and if this process has read 940 permissions on it. 941 */ 942 bool IsFileReadable() const; 943 944 /** 945 Returns @true if a file with this name exists and if this process has read 946 permissions on it. 947 */ 948 static bool IsFileReadable(const wxString& file); 949 950 /** 951 Returns @true if a file with this name exists and if this process has write 952 permissions on it. 953 */ 954 bool IsFileWritable() const; 955 956 /** 957 Returns @true if a file with this name exists and if this process has write 958 permissions on it. 959 */ 960 static bool IsFileWritable(const wxString& file); 961 962 /** 963 Returns @true if the filename is valid, @false if it is not initialized yet. 964 The assignment functions and Clear() may reset the object to the uninitialized, 965 invalid state (the former only do it on failure). 966 */ 967 bool IsOk() const; 968 969 /** 970 Returns @true if the char is a path separator for this format. 971 */ 972 static bool IsPathSeparator(wxChar ch, 973 wxPathFormat format = wxPATH_NATIVE); 974 975 /** 976 Returns @true if the volume part of the path is a unique volume name. 977 978 This function will always return @false if the path format is not 979 wxPATH_DOS. 980 981 Unique volume names are Windows volume identifiers which remain the same 982 regardless of where the volume is actually mounted. Example of a path 983 using a volume name could be 984 @code 985 \\?\Volume{8089d7d7-d0ac-11db-9dd0-806d6172696f}\Program Files\setup.exe 986 @endcode 987 988 @since 2.9.1 989 */ 990 static bool IsMSWUniqueVolumeNamePath(const wxString& path, 991 wxPathFormat format = wxPATH_NATIVE); 992 993 /** 994 Returns @true if this filename is not absolute. 995 */ 996 bool IsRelative(wxPathFormat format = wxPATH_NATIVE) const; 997 998 /** 999 Make the file name absolute. 1000 This is a shortcut for 1001 @code 1002 wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | 1003 wxPATH_NORM_TILDE, cwd, format) 1004 @endcode 1005 1006 @see MakeRelativeTo(), Normalize(), IsAbsolute() 1007 */ 1008 bool MakeAbsolute(const wxString& cwd = wxEmptyString, 1009 wxPathFormat format = wxPATH_NATIVE); 1010 1011 /** 1012 This function tries to put this file name in a form relative to 1013 @a pathBase. 1014 In other words, it returns the file name which should be used to access 1015 this file if the current directory were pathBase. 1016 1017 @param pathBase 1018 The directory to use as root, current directory is used by default 1019 @param format 1020 The file name format, native by default 1021 1022 @return @true if the file name has been changed, @false if we failed to do 1023 anything with it (currently this only happens if the file name 1024 is on a volume different from the volume specified by @a pathBase). 1025 1026 @see Normalize() 1027 */ 1028 bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, 1029 wxPathFormat format = wxPATH_NATIVE); 1030 1031 /** 1032 Creates a directory. 1033 1034 @param perm 1035 The permissions for the newly created directory. 1036 See the ::wxPosixPermissions enumeration for more info. 1037 @param flags 1038 If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each 1039 directory in the path and also don't return an error if the target 1040 directory already exists. 1041 1042 @return Returns @true if the directory was successfully created, @false 1043 otherwise. 1044 */ 1045 bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0) const; 1046 1047 /** 1048 Creates a directory. 1049 1050 @param dir 1051 The directory to create 1052 @param perm 1053 The permissions for the newly created directory. 1054 See the ::wxPosixPermissions enumeration for more info. 1055 @param flags 1056 If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each 1057 directory in the path and also don't return an error if the target 1058 directory already exists. 1059 1060 @return Returns @true if the directory was successfully created, @false 1061 otherwise. 1062 */ 1063 static bool Mkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT, 1064 int flags = 0); 1065 1066 /** 1067 Normalize the path. 1068 1069 With the default flags value, the path will be made absolute, without 1070 any ".." and "." and all environment variables will be expanded in it. 1071 1072 Notice that in some rare cases normalizing a valid path may result in 1073 an invalid wxFileName object. E.g. normalizing "./" path using 1074 wxPATH_NORM_DOTS but not wxPATH_NORM_ABSOLUTE will result in a 1075 completely empty and thus invalid object. As long as there is a non 1076 empty file name the result of normalization will be valid however. 1077 1078 @param flags 1079 The kind of normalization to do with the file name. It can be 1080 any or-combination of the ::wxPathNormalize enumeration values. 1081 @param cwd 1082 If not empty, this directory will be used instead of current 1083 working directory in normalization (see @c wxPATH_NORM_ABSOLUTE). 1084 @param format 1085 The file name format to use when processing the paths, native by default. 1086 1087 @return @true if normalization was successfully or @false otherwise. 1088 */ 1089 bool Normalize(int flags = wxPATH_NORM_ALL, 1090 const wxString& cwd = wxEmptyString, 1091 wxPathFormat format = wxPATH_NATIVE); 1092 1093 /** 1094 Prepends a directory to the file path. 1095 Please see AppendDir() for important notes. 1096 */ 1097 void PrependDir(const wxString& dir); 1098 1099 /** 1100 Removes the specified directory component from the path. 1101 1102 @see GetDirCount() 1103 */ 1104 void RemoveDir(size_t pos); 1105 1106 /** 1107 Removes last directory component from the path. 1108 */ 1109 void RemoveLastDir(); 1110 1111 /** 1112 If the path contains the value of the environment variable named @a envname 1113 then this function replaces it with the string obtained from 1114 wxString::Format(replacementFmtString, value_of_envname_variable). 1115 1116 This function is useful to make the path shorter or to make it dependent 1117 from a certain environment variable. 1118 Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this 1119 function (depending on the value of @a replacementFmtString). 1120 1121 The name and extension of this filename are not modified. 1122 1123 Example: 1124 @code 1125 wxFileName fn("/usr/openwin/lib/someFile"); 1126 fn.ReplaceEnvVariable("OPENWINHOME"); 1127 // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile" 1128 @endcode 1129 1130 @since 2.9.0 1131 1132 @return @true if the operation was successful (which doesn't mean 1133 that something was actually replaced, just that ::wxGetEnv 1134 didn't fail). 1135 */ 1136 bool ReplaceEnvVariable(const wxString& envname, 1137 const wxString& replacementFmtString = "$%s", 1138 wxPathFormat format = wxPATH_NATIVE); 1139 1140 /** 1141 Replaces, if present in the path, the home directory for the given user 1142 (see ::wxGetHomeDir) with a tilde (~). 1143 1144 Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this 1145 function. 1146 1147 The name and extension of this filename are not modified. 1148 1149 @since 2.9.0 1150 1151 @return @true if the operation was successful (which doesn't mean 1152 that something was actually replaced, just that ::wxGetHomeDir 1153 didn't fail). 1154 */ 1155 bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE); 1156 1157 /** 1158 Find the absolute path of the file/directory that is pointed to by this 1159 path. 1160 1161 If this path isn't a symlink, then this function will return the current 1162 path. If the path does not exist on disk, An empty wxFileName instance 1163 will be returned. 1164 1165 @note This is only supported on Unix-like platforms (e.g. wxGTK, wxOSX), 1166 on other platforms (e.g. wxMSW) this function just returns the 1167 current path. 1168 1169 @since 3.1.5 1170 1171 @return The absolute path that the current symlink path points to. 1172 */ 1173 wxFileName ResolveLink(); 1174 1175 1176 /** 1177 Deletes the specified directory from the file system. 1178 1179 @param flags 1180 Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By 1181 default contains neither so the directory will not be removed 1182 unless it is empty. 1183 1184 @return Returns @true if the directory was successfully deleted, @false 1185 otherwise. 1186 */ 1187 bool Rmdir(int flags = 0) const; 1188 1189 /** 1190 Deletes the specified directory from the file system. 1191 1192 @param dir 1193 The directory to delete 1194 @param flags 1195 Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By 1196 default contains neither so the directory will not be removed 1197 unless it is empty. 1198 1199 @return Returns @true if the directory was successfully deleted, @false 1200 otherwise. 1201 */ 1202 static bool Rmdir(const wxString& dir, int flags = 0); 1203 1204 /** 1205 Compares the filename using the rules of this platform. 1206 */ 1207 bool SameAs(const wxFileName& filepath, 1208 wxPathFormat format = wxPATH_NATIVE) const; 1209 1210 /** 1211 Changes the current working directory. 1212 */ 1213 bool SetCwd() const; 1214 1215 /** 1216 Changes the current working directory. 1217 */ 1218 static bool SetCwd(const wxString& cwd); 1219 1220 /** 1221 Sets the extension of the file name to be an empty extension. 1222 This is different from having no extension at all as the file 1223 name will have a trailing dot after a call to this method. 1224 1225 @see SetExt(), ClearExt() 1226 */ 1227 void SetEmptyExt(); 1228 1229 /** 1230 Sets the extension of the file name. 1231 1232 Setting an empty string as the extension will remove the extension 1233 resulting in a file name without a trailing dot, unlike a call to 1234 SetEmptyExt(). 1235 1236 @see SetEmptyExt(), ClearExt() 1237 */ 1238 void SetExt(const wxString& ext); 1239 1240 /** 1241 The full name is the file name and extension (but without the path). 1242 */ 1243 void SetFullName(const wxString& fullname); 1244 1245 /** 1246 Sets the name part (without extension). 1247 1248 @see SetFullName() 1249 */ 1250 void SetName(const wxString& name); 1251 1252 /** 1253 Sets the path. 1254 1255 The @a path argument includes both the path and the volume, if 1256 supported by @a format. 1257 1258 Calling this function doesn't affect the name and extension components, 1259 to change them as well you can use Assign() or just an assignment 1260 operator. 1261 1262 @see GetPath() 1263 */ 1264 void SetPath(const wxString& path, wxPathFormat format = wxPATH_NATIVE); 1265 1266 /** 1267 Sets permissions for this file or directory. 1268 1269 @param permissions 1270 The new permissions: this should be a combination of 1271 ::wxPosixPermissions enum elements. 1272 1273 @since 3.0 1274 1275 @note If this is a symbolic link and it should not be followed 1276 this call will fail. 1277 1278 @return @true on success, @false if an error occurred (for example, 1279 the file doesn't exist). 1280 */ 1281 bool SetPermissions(int permissions); 1282 1283 /** 1284 Converts URL into a well-formed filename. 1285 The URL must use the @c file protocol. 1286 If the URL does not use @c file protocol 1287 wxFileName object may not be good or may not exist 1288 1289 @since 3.1.3 1290 */ 1291 static wxFileName URLToFileName(const wxString& url); 1292 1293 /** 1294 Converts wxFileName into an URL. 1295 1296 @see URLToFileName(), wxFileName 1297 1298 @since 3.1.3 1299 */ 1300 static wxString FileNameToURL(const wxFileName& filename); 1301 1302 /** 1303 Sets the file creation and last access/modification times (any of the pointers 1304 may be @NULL). 1305 1306 Notice that the file creation time can't be changed under Unix, so @a 1307 dtCreate is ignored there (but @true is still returned). Under Windows 1308 all three times can be set. 1309 */ 1310 bool SetTimes(const wxDateTime* dtAccess, 1311 const wxDateTime* dtMod, 1312 const wxDateTime* dtCreate) const; 1313 1314 /** 1315 Sets the volume specifier. 1316 */ 1317 void SetVolume(const wxString& volume); 1318 1319 /** 1320 Return whether some operations will follow symlink. 1321 1322 By default, file operations "follow symlink", i.e. operate on its 1323 target and not on the symlink itself. See DontFollowLink() for more 1324 information. 1325 1326 @since 2.9.5 1327 */ 1328 bool ShouldFollowLink() const; 1329 1330 //@{ 1331 /** 1332 This function splits a full file name into components: the volume (with the 1333 first version) path (including the volume in the second version), the base name 1334 and the extension. 1335 1336 Any of the output parameters (@e volume, @e path, @a name or @e ext) may 1337 be @NULL if you are not interested in the value of a particular component. 1338 Also, @a fullpath may be empty on entry. 1339 On return, @a path contains the file path (without the trailing separator), 1340 @a name contains the file name and @a ext contains the file extension 1341 without leading dot. All three of them may be empty if the corresponding 1342 component is. The old contents of the strings pointed to by these parameters 1343 will be overwritten in any case (if the pointers are not @NULL). 1344 1345 Note that for a filename "foo." the extension is present, as indicated by the 1346 trailing dot, but empty. If you need to cope with such cases, you should use 1347 @a hasExt instead of relying on testing whether @a ext is empty or not. 1348 */ 1349 static void SplitPath(const wxString& fullpath, 1350 wxString* volume, 1351 wxString* path, 1352 wxString* name, 1353 wxString* ext, 1354 bool* hasExt = NULL, 1355 wxPathFormat format = wxPATH_NATIVE); 1356 static void SplitPath(const wxString& fullpath, 1357 wxString* volume, 1358 wxString* path, 1359 wxString* name, 1360 wxString* ext, 1361 wxPathFormat format); 1362 static void SplitPath(const wxString& fullpath, 1363 wxString* path, 1364 wxString* name, 1365 wxString* ext, 1366 wxPathFormat format = wxPATH_NATIVE); 1367 //@} 1368 1369 /** 1370 Splits the given @a fullpath into the volume part (which may be empty) and 1371 the pure path part, not containing any volume. 1372 1373 @see SplitPath() 1374 */ 1375 static void SplitVolume(const wxString& fullpath, 1376 wxString* volume, 1377 wxString* path, 1378 wxPathFormat format = wxPATH_NATIVE); 1379 1380 1381 /** 1382 Strip the file extension. 1383 1384 This function does more than just removing everything after the last 1385 period from the string, for example it will return the string ".vimrc" 1386 unchanged because the part after the period is not an extension but the 1387 file name in this case. You can use wxString::BeforeLast() to really 1388 get just the part before the last period (but notice that that function 1389 returns empty string if period is not present at all unlike this 1390 function which returns the @a fullname unchanged in this case). 1391 1392 @param fullname 1393 File path including name and, optionally, extension. 1394 1395 @return 1396 File path without extension 1397 1398 @since 2.9.0 1399 */ 1400 static wxString StripExtension(const wxString& fullname); 1401 1402 /** 1403 Sets the access and modification times to the current moment. 1404 */ 1405 bool Touch() const; 1406 1407 /** 1408 Returns @true if the filenames are different. The string @e filenames 1409 is interpreted as a path in the native filename format. 1410 */ 1411 bool operator!=(const wxFileName& filename) const; 1412 1413 /** 1414 Returns @true if the filenames are different. The string @e filenames 1415 is interpreted as a path in the native filename format. 1416 */ 1417 bool operator!=(const wxString& filename) const; 1418 1419 /** 1420 Returns @true if the filenames are equal. The string @e filenames is 1421 interpreted as a path in the native filename format. 1422 */ 1423 bool operator==(const wxFileName& filename) const; 1424 1425 /** 1426 Returns @true if the filenames are equal. The string @e filenames is 1427 interpreted as a path in the native filename format. 1428 */ 1429 bool operator==(const wxString& filename) const; 1430 1431 /** 1432 Assigns the new value to this filename object. 1433 */ 1434 wxFileName& operator=(const wxFileName& filename); 1435 1436 /** 1437 Assigns the new value to this filename object. 1438 */ 1439 wxFileName& operator=(const wxString& filename); 1440 }; 1441