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