avoid infinite recursion for richtooltops, (hopefully) fixes #15070
[wxWidgets.git] / interface / wx / filename.h
0 / 1383 (  0%)
CommitLineData
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*/
17enum 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*/
38enum 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*/
56enum 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 */
78enum
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 */
98enum
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*/
120wxULongLong 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*/
295class wxFileName
296{
297public:
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};