]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: filename.h | |
e54c96f1 | 3 | // Purpose: interface of wxFileName |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxFileName | |
11 | @wxheader{filename.h} | |
7c913512 | 12 | |
23324ae1 FM |
13 | wxFileName encapsulates a file name. This class serves two purposes: first, it |
14 | provides the functions to split the file names into components and to recombine | |
15 | these components in the full file name which can then be passed to the OS file | |
16 | functions (and @ref overview_filefunctions "wxWidgets functions" wrapping them). | |
17 | Second, it includes the functions for working with the files itself. Note that | |
18 | to change the file data you should use wxFile class instead. | |
19 | wxFileName provides functions for working with the file attributes. | |
7c913512 | 20 | |
23324ae1 FM |
21 | When working with directory names (i.e. without filename and extension) |
22 | make sure not to misuse the file name part of this class with the last | |
23 | directory. Instead initialize the wxFileName instance like this: | |
7c913512 | 24 | |
23324ae1 FM |
25 | @code |
26 | wxFileName dirname( "C:\mydir", "" ); | |
27 | MyMethod( dirname.GetPath() ); | |
28 | @endcode | |
7c913512 | 29 | |
23324ae1 | 30 | The same can be done using the static method wxFileName::DirName: |
7c913512 | 31 | |
23324ae1 FM |
32 | @code |
33 | wxFileName dirname = wxFileName::DirName( "C:\mydir" ); | |
34 | MyMethod( dirname.GetPath() ); | |
35 | @endcode | |
7c913512 | 36 | |
23324ae1 FM |
37 | Accordingly, methods dealing with directories or directory names |
38 | like wxFileName::IsDirReadable use | |
7c913512 | 39 | wxFileName::GetPath whereas methods dealing |
23324ae1 FM |
40 | with file names like wxFileName::IsFileReadable |
41 | use wxFileName::GetFullPath. | |
7c913512 | 42 | |
23324ae1 FM |
43 | If it is not known wether a string contains a directory name or |
44 | a complete file name (such as when interpreting user input) you need to use | |
45 | the static function wxFileName::DirExists | |
46 | (or its identical variants wxDir::Exists and | |
e54c96f1 | 47 | wxDirExists()) and construct the wxFileName |
23324ae1 FM |
48 | instance accordingly. This will only work if the directory actually exists, |
49 | of course: | |
7c913512 | 50 | |
23324ae1 FM |
51 | @code |
52 | wxString user_input; | |
53 | // get input from user | |
7c913512 | 54 | |
23324ae1 FM |
55 | wxFileName fname; |
56 | if (wxDirExists(user_input)) | |
57 | fname.AssignDir( user_input ); | |
58 | else | |
59 | fname.Assign( user_input ); | |
60 | @endcode | |
7c913512 | 61 | |
23324ae1 FM |
62 | @library{wxbase} |
63 | @category{file} | |
7c913512 | 64 | |
e54c96f1 | 65 | @see wxFileName::GetCwd |
23324ae1 | 66 | */ |
7c913512 | 67 | class wxFileName |
23324ae1 FM |
68 | { |
69 | public: | |
70 | //@{ | |
71 | /** | |
72 | Constructor from a volume name, a directory name, base file name and extension. | |
73 | */ | |
74 | wxFileName(); | |
7c913512 FM |
75 | wxFileName(const wxFileName& filename); |
76 | wxFileName(const wxString& fullpath, | |
77 | wxPathFormat format = wxPATH_NATIVE); | |
78 | wxFileName(const wxString& path, const wxString& name, | |
79 | wxPathFormat format = wxPATH_NATIVE); | |
80 | wxFileName(const wxString& path, const wxString& name, | |
81 | const wxString& ext, | |
82 | wxPathFormat format = wxPATH_NATIVE); | |
83 | wxFileName(const wxString& volume, const wxString& path, | |
84 | const wxString& name, | |
85 | const wxString& ext, | |
86 | wxPathFormat format = wxPATH_NATIVE); | |
23324ae1 FM |
87 | //@} |
88 | ||
89 | /** | |
90 | Appends a directory component to the path. This component should contain a | |
91 | single directory name level, i.e. not contain any path or volume separators nor | |
92 | should it be empty, otherwise the function does nothing (and generates an | |
93 | assert failure in debug build). | |
94 | */ | |
95 | void AppendDir(const wxString& dir); | |
96 | ||
97 | //@{ | |
98 | /** | |
99 | Creates the file name from various combinations of data. | |
100 | */ | |
101 | void Assign(const wxFileName& filepath); | |
7c913512 FM |
102 | void Assign(const wxString& fullpath, |
103 | wxPathFormat format = wxPATH_NATIVE); | |
104 | void Assign(const wxString& volume, const wxString& path, | |
105 | const wxString& name, | |
106 | const wxString& ext, | |
107 | bool hasExt, | |
108 | wxPathFormat format = wxPATH_NATIVE); | |
109 | void Assign(const wxString& volume, const wxString& path, | |
110 | const wxString& name, | |
111 | const wxString& ext, | |
112 | wxPathFormat format = wxPATH_NATIVE); | |
113 | void Assign(const wxString& path, const wxString& name, | |
114 | wxPathFormat format = wxPATH_NATIVE); | |
115 | void Assign(const wxString& path, const wxString& name, | |
116 | const wxString& ext, | |
117 | wxPathFormat format = wxPATH_NATIVE); | |
23324ae1 FM |
118 | //@} |
119 | ||
120 | /** | |
121 | Makes this object refer to the current working directory on the specified | |
4cc4bfaf | 122 | volume (or current volume if @a volume is empty). |
3c4f71cc | 123 | |
4cc4bfaf | 124 | @see GetCwd() |
23324ae1 FM |
125 | */ |
126 | static void AssignCwd(const wxString& volume = wxEmptyString); | |
127 | ||
128 | /** | |
129 | Sets this file name object to the given directory name. The name and extension | |
130 | will be empty. | |
131 | */ | |
132 | void AssignDir(const wxString& dir, | |
133 | wxPathFormat format = wxPATH_NATIVE); | |
134 | ||
135 | /** | |
136 | Sets this file name object to the home directory. | |
137 | */ | |
138 | void AssignHomeDir(); | |
139 | ||
140 | /** | |
141 | The function calls CreateTempFileName() to | |
142 | create a temporary file and sets this object to the name of the file. If a | |
143 | temporary file couldn't be created, the object is put into the | |
144 | @ref isok() invalid state. | |
145 | */ | |
146 | void AssignTempFileName(const wxString& prefix, | |
4cc4bfaf | 147 | wxFile* fileTemp = NULL); |
23324ae1 FM |
148 | |
149 | /** | |
150 | Reset all components to default, uninitialized state. | |
151 | */ | |
152 | void Clear(); | |
153 | ||
154 | /** | |
7c913512 | 155 | Removes the extension from the file name resulting in a |
23324ae1 | 156 | file name with no trailing dot. |
3c4f71cc | 157 | |
4cc4bfaf | 158 | @see SetExt(), SetEmptyExt() |
23324ae1 FM |
159 | */ |
160 | void SetClearExt(); | |
161 | ||
162 | /** | |
163 | Returns a temporary file name starting with the given @e prefix. If | |
4cc4bfaf | 164 | the @a prefix is an absolute path, the temporary file is created in this |
23324ae1 FM |
165 | directory, otherwise it is created in the default system directory for the |
166 | temporary files or in the current directory. | |
23324ae1 | 167 | If the function succeeds, the temporary file is actually created. If |
4cc4bfaf | 168 | @a fileTemp is not @NULL, this file will be opened using the name of |
23324ae1 FM |
169 | the temporary file. When possible, this is done in an atomic way ensuring that |
170 | no race condition occurs between the temporary file name generation and opening | |
171 | it which could often lead to security compromise on the multiuser systems. | |
4cc4bfaf | 172 | If @a fileTemp is @NULL, the file is only created, but not opened. |
23324ae1 FM |
173 | Under Unix, the temporary file will have read and write permissions for the |
174 | owner only to minimize the security problems. | |
3c4f71cc | 175 | |
7c913512 | 176 | @param prefix |
4cc4bfaf | 177 | Prefix to use for the temporary file name construction |
7c913512 | 178 | @param fileTemp |
4cc4bfaf | 179 | The file to open or @NULL to just get the name |
3c4f71cc | 180 | |
d29a9a8a | 181 | @return The full temporary file name or an empty string on error. |
23324ae1 FM |
182 | */ |
183 | static wxString CreateTempFileName(const wxString& prefix, | |
4cc4bfaf | 184 | wxFile* fileTemp = NULL); |
23324ae1 FM |
185 | |
186 | //@{ | |
187 | /** | |
188 | Returns @true if the directory with this name exists. | |
189 | */ | |
190 | bool DirExists(); | |
328f5751 | 191 | const static bool DirExists(const wxString& dir); |
23324ae1 FM |
192 | //@} |
193 | ||
194 | /** | |
195 | Returns the object corresponding to the directory with the given name. | |
4cc4bfaf | 196 | The @a dir parameter may have trailing path separator or not. |
23324ae1 FM |
197 | */ |
198 | static wxFileName DirName(const wxString& dir, | |
199 | wxPathFormat format = wxPATH_NATIVE); | |
200 | ||
201 | /** | |
202 | These functions allow to examine and modify the individual directories of the | |
203 | path: | |
23324ae1 | 204 | AppendDir() |
3c4f71cc | 205 | |
23324ae1 | 206 | InsertDir() |
3c4f71cc | 207 | |
23324ae1 FM |
208 | GetDirCount() |
209 | PrependDir() | |
3c4f71cc | 210 | |
23324ae1 | 211 | RemoveDir() |
3c4f71cc | 212 | |
23324ae1 | 213 | RemoveLastDir() |
23324ae1 FM |
214 | To change the components of the file name individually you can use the |
215 | following functions: | |
23324ae1 | 216 | GetExt() |
3c4f71cc | 217 | |
23324ae1 | 218 | GetName() |
3c4f71cc | 219 | |
23324ae1 | 220 | GetVolume() |
3c4f71cc | 221 | |
23324ae1 | 222 | HasExt() |
3c4f71cc | 223 | |
23324ae1 | 224 | HasName() |
3c4f71cc | 225 | |
23324ae1 | 226 | HasVolume() |
3c4f71cc | 227 | |
23324ae1 | 228 | SetExt() |
3c4f71cc | 229 | |
23324ae1 | 230 | ClearExt() |
3c4f71cc | 231 | |
23324ae1 | 232 | SetEmptyExt() |
3c4f71cc | 233 | |
23324ae1 | 234 | SetName() |
3c4f71cc | 235 | |
23324ae1 FM |
236 | SetVolume() |
237 | */ | |
238 | ||
239 | ||
240 | /** | |
241 | You can initialize a wxFileName instance using one of the following functions: | |
23324ae1 | 242 | @ref wxfilename() "wxFileName constructors" |
3c4f71cc | 243 | |
23324ae1 | 244 | Assign() |
3c4f71cc | 245 | |
23324ae1 | 246 | AssignCwd() |
3c4f71cc | 247 | |
23324ae1 | 248 | AssignDir() |
3c4f71cc | 249 | |
23324ae1 | 250 | AssignHomeDir() |
3c4f71cc | 251 | |
23324ae1 | 252 | @ref assigntempfilename() AssignHomeTempFileName |
3c4f71cc | 253 | |
23324ae1 | 254 | DirName() |
3c4f71cc | 255 | |
23324ae1 | 256 | FileName() |
3c4f71cc | 257 | |
23324ae1 FM |
258 | @ref operatorassign() "operator =" |
259 | */ | |
260 | ||
261 | ||
262 | /** | |
263 | wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS | |
264 | and VMS formats. Although these formats are quite different, wxFileName tries | |
265 | to treat them all in the same generic way. It supposes that all file names | |
266 | consist of the following parts: the volume (also known as drive under Windows | |
267 | or device under VMS), the path which is a sequence of directory names separated | |
268 | by the @ref getpathseparators() "path separators" and the full | |
269 | filename itself which, in turn, is composed from the base file name and the | |
270 | extension. All of the individual components of the file name may be empty and, | |
271 | for example, the volume name is always empty under Unix, but if they are all | |
272 | empty simultaneously, the filename object is considered to be in an invalid | |
273 | state and IsOk() returns @false for it. | |
23324ae1 FM |
274 | File names can be case-sensitive or not, the function |
275 | IsCaseSensitive() allows to determine this. | |
23324ae1 FM |
276 | The rules for determining whether the file name is absolute or relative also |
277 | depend on the file name format and the only portable way to answer this | |
278 | question is to use IsAbsolute() or | |
279 | IsRelative() method. Note that on Windows, "X:" | |
280 | refers to the current working directory on drive X. Therefore, a wxFileName | |
7c913512 | 281 | instance constructed from for example "X:dir/file.ext" treats the portion |
23324ae1 | 282 | beyond drive separator as being relative to that directory. |
23324ae1 FM |
283 | To ensure that the filename is absolute, you may use |
284 | MakeAbsolute(). There is also an inverse | |
285 | function MakeRelativeTo() which undoes | |
286 | what @ref normalize() Normalize(wxPATH_NORM_DOTS) does. | |
23324ae1 FM |
287 | Other functions returning information about the file format provided by this |
288 | class are GetVolumeSeparator(), | |
289 | IsPathSeparator(). | |
290 | */ | |
291 | ||
292 | ||
293 | /** | |
294 | Before doing other tests, you should use IsOk() to | |
295 | verify that the filename is well defined. If it is, | |
296 | FileExists() can be used to test whether a file | |
297 | with such name exists and DirExists() can be used | |
298 | to test for directory existence. | |
23324ae1 FM |
299 | File names should be compared using SameAs() method |
300 | or @ref operatorequal() "operator ==". | |
23324ae1 | 301 | For testing basic access modes, you can use: |
23324ae1 | 302 | IsDirWritable() |
3c4f71cc | 303 | |
23324ae1 | 304 | IsDirReadable() |
3c4f71cc | 305 | |
23324ae1 | 306 | IsFileWritable() |
3c4f71cc | 307 | |
23324ae1 | 308 | IsFileReadable() |
3c4f71cc | 309 | |
23324ae1 FM |
310 | IsFileExecutable() |
311 | */ | |
312 | ||
313 | ||
314 | //@{ | |
315 | /** | |
316 | Returns @true if the file with this name exists. | |
3c4f71cc | 317 | |
4cc4bfaf | 318 | @see DirExists() |
23324ae1 FM |
319 | */ |
320 | bool FileExists(); | |
328f5751 | 321 | const static bool FileExists(const wxString& file); |
23324ae1 FM |
322 | //@} |
323 | ||
324 | /** | |
325 | Returns the file name object corresponding to the given @e file. This | |
326 | function exists mainly for symmetry with DirName(). | |
327 | */ | |
328 | static wxFileName FileName(const wxString& file, | |
329 | wxPathFormat format = wxPATH_NATIVE); | |
330 | ||
331 | /** | |
332 | Retrieves the value of the current working directory on the specified volume. If | |
333 | the volume is empty, the program's current working directory is returned for the | |
334 | current volume. | |
3c4f71cc | 335 | |
d29a9a8a | 336 | @return The string containing the current working directory or an empty |
4cc4bfaf | 337 | string on error. |
3c4f71cc | 338 | |
4cc4bfaf | 339 | @see AssignCwd() |
23324ae1 FM |
340 | */ |
341 | static wxString GetCwd(const wxString& volume = ""); | |
342 | ||
343 | /** | |
344 | Returns the number of directories in the file name. | |
345 | */ | |
328f5751 | 346 | size_t GetDirCount() const; |
23324ae1 FM |
347 | |
348 | /** | |
349 | Returns the directories in string array form. | |
350 | */ | |
328f5751 | 351 | const wxArrayString GetDirs() const; |
23324ae1 FM |
352 | |
353 | /** | |
354 | Returns the file name extension. | |
355 | */ | |
328f5751 | 356 | wxString GetExt() const; |
23324ae1 FM |
357 | |
358 | /** | |
359 | Returns the characters that can't be used in filenames and directory names for | |
360 | the specified format. | |
361 | */ | |
362 | static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); | |
363 | ||
364 | /** | |
365 | Returns the canonical path format for this platform. | |
366 | */ | |
367 | static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE); | |
368 | ||
369 | /** | |
370 | Returns the full name (including extension but excluding directories). | |
371 | */ | |
328f5751 | 372 | wxString GetFullName() const; |
23324ae1 FM |
373 | |
374 | /** | |
375 | Returns the full path with name and extension. | |
376 | */ | |
328f5751 | 377 | wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
378 | |
379 | /** | |
380 | Returns the home directory. | |
381 | */ | |
382 | static wxString GetHomeDir(); | |
383 | ||
384 | //@{ | |
385 | /** | |
386 | Returns the size of this file (first form) or the given number of bytes (second | |
387 | form) | |
388 | in a human-readable form. | |
23324ae1 FM |
389 | If the size could not be retrieved the @c failmsg string is returned (first |
390 | form). | |
391 | If @c bytes is @c wxInvalidSize or zero, then @c nullsize is returned (second | |
392 | form). | |
23324ae1 FM |
393 | In case of success, the returned string is a floating-point number with @c |
394 | precision decimal digits | |
395 | followed by the size unit (B, kB, MB, GB, TB: respectively bytes, kilobytes, | |
396 | megabytes, gigabytes, terabytes). | |
397 | */ | |
398 | wxString GetHumanReadableSize(const wxString& failmsg = "Not available", | |
399 | int precision = 1); | |
328f5751 FM |
400 | const static wxString GetHumanReadableSize(const wxULongLong& bytes, |
401 | const wxString& nullsize = "Not available", | |
402 | int precision = 1); | |
23324ae1 FM |
403 | //@} |
404 | ||
405 | /** | |
406 | Return the long form of the path (returns identity on non-Windows platforms) | |
407 | */ | |
328f5751 | 408 | wxString GetLongPath() const; |
23324ae1 FM |
409 | |
410 | /** | |
411 | Returns the last time the file was last modified. | |
412 | */ | |
328f5751 | 413 | wxDateTime GetModificationTime() const; |
23324ae1 FM |
414 | |
415 | /** | |
416 | Returns the name part of the filename (without extension). | |
3c4f71cc | 417 | |
4cc4bfaf | 418 | @see GetFullName() |
23324ae1 | 419 | */ |
328f5751 | 420 | wxString GetName() const; |
23324ae1 FM |
421 | |
422 | /** | |
423 | Returns the path part of the filename (without the name or extension). The | |
424 | possible flags values are: | |
3c4f71cc | 425 | |
23324ae1 | 426 | @b wxPATH_GET_VOLUME |
3c4f71cc | 427 | |
23324ae1 FM |
428 | Return the path with the volume (does |
429 | nothing for the filename formats without volumes), otherwise the path without | |
430 | volume part is returned. | |
3c4f71cc | 431 | |
23324ae1 | 432 | @b wxPATH_GET_SEPARATOR |
3c4f71cc | 433 | |
23324ae1 FM |
434 | Return the path with the trailing |
435 | separator, if this flag is not given there will be no separator at the end of | |
436 | the path. | |
437 | */ | |
438 | wxString GetPath(int flags = wxPATH_GET_VOLUME, | |
328f5751 | 439 | wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
440 | |
441 | /** | |
7c913512 | 442 | Returns the usually used path separator for this format. For all formats but |
23324ae1 FM |
443 | @c wxPATH_DOS there is only one path separator anyhow, but for DOS there |
444 | are two of them and the native one, i.e. the backslash is returned by this | |
445 | method. | |
3c4f71cc | 446 | |
4cc4bfaf | 447 | @see GetPathSeparators() |
23324ae1 FM |
448 | */ |
449 | static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); | |
450 | ||
451 | /** | |
452 | Returns the string containing all the path separators for this format. For all | |
453 | formats but @c wxPATH_DOS this string contains only one character but for | |
454 | DOS and Windows both @c '/' and @c '\' may be used as | |
455 | separators. | |
3c4f71cc | 456 | |
4cc4bfaf | 457 | @see GetPathSeparator() |
23324ae1 FM |
458 | */ |
459 | static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); | |
460 | ||
461 | /** | |
462 | Returns the string of characters which may terminate the path part. This is the | |
463 | same as GetPathSeparators() except for VMS | |
464 | path format where ] is used at the end of the path part. | |
465 | */ | |
466 | static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); | |
467 | ||
468 | /** | |
469 | Returns the path with the trailing separator, useful for appending the name to | |
470 | the given path. | |
23324ae1 FM |
471 | This is the same as calling GetPath() |
472 | @c (wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format). | |
473 | */ | |
328f5751 | 474 | wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
475 | |
476 | /** | |
477 | Return the short form of the path (returns identity on non-Windows platforms). | |
478 | */ | |
328f5751 | 479 | wxString GetShortPath() const; |
23324ae1 FM |
480 | |
481 | //@{ | |
482 | /** | |
483 | Returns the size of this file (first form) or the size of the given file | |
484 | (second form). | |
485 | If the file does not exist or its size could not be read (because e.g. the file | |
486 | is locked | |
487 | by another process) the returned value is @c wxInvalidSize. | |
488 | */ | |
489 | wxULongLong GetSize(); | |
328f5751 | 490 | const static wxULongLong GetSize(const wxString& filename); |
23324ae1 FM |
491 | //@} |
492 | ||
493 | /** | |
494 | Returns the directory used for temporary files. | |
495 | */ | |
496 | static wxString GetTempDir(); | |
497 | ||
498 | /** | |
499 | Returns the last access, last modification and creation times. The last access | |
500 | time is updated whenever the file is read or written (or executed in the case | |
501 | of Windows), last modification time is only changed when the file is written | |
502 | to. Finally, the creation time is indeed the time when the file was created | |
503 | under Windows and the inode change time under Unix (as it is impossible to | |
504 | retrieve the real file creation time there anyhow) which can also be changed | |
505 | by many operations after the file creation. | |
23324ae1 FM |
506 | If no filename or extension is specified in this instance of wxFileName |
507 | (and therefore IsDir() returns @true) then | |
508 | this function will return the directory times of the path specified by | |
509 | GetPath(), otherwise the file times of the | |
510 | file specified by GetFullPath(). | |
23324ae1 FM |
511 | Any of the pointers may be @NULL if the corresponding time is not |
512 | needed. | |
3c4f71cc | 513 | |
d29a9a8a | 514 | @return @true on success, @false if we failed to retrieve the times. |
23324ae1 FM |
515 | */ |
516 | bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod, | |
328f5751 | 517 | wxDateTime* dtCreate) const; |
23324ae1 FM |
518 | |
519 | /** | |
520 | Returns the string containing the volume for this file name, empty if it | |
521 | doesn't have one or if the file system doesn't support volumes at all (for | |
522 | example, Unix). | |
523 | */ | |
328f5751 | 524 | wxString GetVolume() const; |
23324ae1 FM |
525 | |
526 | /** | |
527 | Returns the string separating the volume from the path for this format. | |
528 | */ | |
529 | static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); | |
530 | ||
531 | /** | |
532 | Returns @true if an extension is present. | |
533 | */ | |
328f5751 | 534 | bool HasExt() const; |
23324ae1 FM |
535 | |
536 | /** | |
537 | Returns @true if a name is present. | |
538 | */ | |
328f5751 | 539 | bool HasName() const; |
23324ae1 FM |
540 | |
541 | /** | |
542 | Returns @true if a volume specifier is present. | |
543 | */ | |
328f5751 | 544 | bool HasVolume() const; |
23324ae1 FM |
545 | |
546 | /** | |
547 | Inserts a directory component before the zero-based position in the directory | |
548 | list. Please see AppendDir() for important notes. | |
549 | */ | |
550 | void InsertDir(size_t before, const wxString& dir); | |
551 | ||
552 | /** | |
553 | Returns @true if this filename is absolute. | |
554 | */ | |
555 | bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE); | |
556 | ||
557 | /** | |
558 | Returns @true if the file names of this type are case-sensitive. | |
559 | */ | |
560 | static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE); | |
561 | ||
562 | /** | |
563 | Returns @true if this object represents a directory, @false otherwise | |
564 | (i.e. if it is a file). Note that this method doesn't test whether the | |
7c913512 FM |
565 | directory or file really exists, you should use |
566 | DirExists() or | |
23324ae1 FM |
567 | FileExists() for this. |
568 | */ | |
328f5751 | 569 | bool IsDir() const; |
23324ae1 FM |
570 | |
571 | //@{ | |
572 | /** | |
573 | Returns @true if the directory component of this instance (or given @e dir) | |
574 | is an existing directory and this process has read permissions on it. | |
575 | Read permissions on a directory mean that you can list the directory contents | |
576 | but it | |
577 | doesn't imply that you have read permissions on the files contained. | |
578 | */ | |
579 | bool IsDirReadable(); | |
328f5751 | 580 | const static bool IsDirReadable(const wxString& dir); |
23324ae1 FM |
581 | //@} |
582 | ||
583 | //@{ | |
584 | /** | |
585 | Returns @true if the directory component of this instance (or given @e dir) | |
586 | is an existing directory and this process has write permissions on it. | |
587 | Write permissions on a directory mean that you can create new files in the | |
588 | directory. | |
589 | */ | |
590 | bool IsDirWritable(); | |
328f5751 | 591 | const static bool IsDirWritable(const wxString& dir); |
23324ae1 FM |
592 | //@} |
593 | ||
594 | //@{ | |
595 | /** | |
596 | Returns @true if a file with this name exists and if this process has execute | |
597 | permissions on it. | |
598 | */ | |
599 | bool IsFileExecutable(); | |
328f5751 | 600 | const static bool IsFileExecutable(const wxString& file); |
23324ae1 FM |
601 | //@} |
602 | ||
603 | //@{ | |
604 | /** | |
605 | Returns @true if a file with this name exists and if this process has read | |
606 | permissions on it. | |
607 | */ | |
608 | bool IsFileReadable(); | |
328f5751 | 609 | const static bool IsFileReadable(const wxString& file); |
23324ae1 FM |
610 | //@} |
611 | ||
612 | //@{ | |
613 | /** | |
614 | Returns @true if a file with this name exists and if this process has write | |
615 | permissions on it. | |
616 | */ | |
617 | bool IsFileWritable(); | |
328f5751 | 618 | const static bool IsFileWritable(const wxString& file); |
23324ae1 FM |
619 | //@} |
620 | ||
621 | /** | |
622 | Returns @true if the filename is valid, @false if it is not | |
623 | initialized yet. The assignment functions and | |
624 | Clear() may reset the object to the uninitialized, | |
625 | invalid state (the former only do it on failure). | |
626 | */ | |
328f5751 | 627 | bool IsOk() const; |
23324ae1 FM |
628 | |
629 | /** | |
630 | Returns @true if the char is a path separator for this format. | |
631 | */ | |
632 | static bool IsPathSeparator(wxChar ch, | |
633 | wxPathFormat format = wxPATH_NATIVE); | |
634 | ||
635 | /** | |
636 | Returns @true if this filename is not absolute. | |
637 | */ | |
638 | bool IsRelative(wxPathFormat format = wxPATH_NATIVE); | |
639 | ||
640 | /** | |
641 | On Mac OS, gets the common type and creator for the given extension. | |
642 | */ | |
643 | static bool MacFindDefaultTypeAndCreator(const wxString& ext, | |
7c913512 FM |
644 | wxUint32* type, |
645 | wxUint32* creator); | |
23324ae1 FM |
646 | |
647 | /** | |
648 | On Mac OS, registers application defined extensions and their default type and | |
649 | creator. | |
650 | */ | |
651 | static void MacRegisterDefaultTypeAndCreator(const wxString& ext, | |
7c913512 FM |
652 | wxUint32 type, |
653 | wxUint32 creator); | |
23324ae1 FM |
654 | |
655 | /** | |
656 | On Mac OS, looks up the appropriate type and creator from the registration and | |
657 | then sets it. | |
658 | */ | |
659 | bool MacSetDefaultTypeAndCreator(); | |
660 | ||
661 | /** | |
662 | Make the file name absolute. This is a shortcut for | |
663 | @c wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | | |
664 | wxPATH_NORM_TILDE, cwd, format). | |
3c4f71cc | 665 | |
4cc4bfaf | 666 | @see MakeRelativeTo(), Normalize(), IsAbsolute() |
23324ae1 FM |
667 | */ |
668 | bool MakeAbsolute(const wxString& cwd = wxEmptyString, | |
669 | wxPathFormat format = wxPATH_NATIVE); | |
670 | ||
671 | /** | |
7c913512 | 672 | This function tries to put this file name in a form relative to |
3c4f71cc | 673 | |
23324ae1 FM |
674 | @param pathBase. |
675 | In other words, it returns the file name which should be used to access this | |
676 | file if the current directory were pathBase. | |
3c4f71cc | 677 | |
7c913512 | 678 | pathBase |
4cc4bfaf FM |
679 | the directory to use as root, current directory is used by |
680 | default | |
7c913512 | 681 | @param format |
4cc4bfaf | 682 | the file name format, native by default |
3c4f71cc | 683 | |
d29a9a8a | 684 | @return @true if the file name has been changed, @false if we failed to do |
4cc4bfaf FM |
685 | anything with it (currently this only happens if the |
686 | file name is on a volume different from the volume | |
687 | specified by pathBase). | |
3c4f71cc | 688 | |
4cc4bfaf | 689 | @see Normalize() |
23324ae1 FM |
690 | */ |
691 | bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, | |
692 | wxPathFormat format = wxPATH_NATIVE); | |
693 | ||
694 | //@{ | |
695 | /** | |
7c913512 | 696 | @param dir |
4cc4bfaf | 697 | the directory to create |
7c913512 | 698 | @param parm |
4cc4bfaf | 699 | the permissions for the newly created directory |
7c913512 | 700 | @param flags |
4cc4bfaf FM |
701 | if the flags contain wxPATH_MKDIR_FULL flag, |
702 | try to create each directory in the path and also don't return an error | |
703 | if the target directory already exists. | |
3c4f71cc | 704 | |
d29a9a8a | 705 | @return Returns @true if the directory was successfully created, @false |
4cc4bfaf | 706 | otherwise. |
23324ae1 FM |
707 | */ |
708 | bool Mkdir(int perm = 0777, int flags = 0); | |
7c913512 FM |
709 | static bool Mkdir(const wxString& dir, int perm = 0777, |
710 | int flags = 0); | |
23324ae1 FM |
711 | //@} |
712 | ||
713 | /** | |
714 | Normalize the path. With the default flags value, the path will be | |
715 | made absolute, without any ".." and "." and all environment | |
716 | variables will be expanded in it. | |
3c4f71cc | 717 | |
7c913512 | 718 | @param flags |
4cc4bfaf FM |
719 | The kind of normalization to do with the file name. It can be |
720 | any or-combination of the following constants: | |
3c4f71cc VS |
721 | |
722 | ||
723 | ||
724 | ||
725 | ||
726 | ||
4cc4bfaf | 727 | wxPATH_NORM_ENV_VARS |
3c4f71cc VS |
728 | |
729 | ||
730 | ||
731 | ||
4cc4bfaf | 732 | replace env vars with their values |
3c4f71cc VS |
733 | |
734 | ||
735 | ||
736 | ||
737 | ||
4cc4bfaf | 738 | wxPATH_NORM_DOTS |
3c4f71cc VS |
739 | |
740 | ||
741 | ||
742 | ||
4cc4bfaf | 743 | squeeze all .. and . when possible; if there are too many .. and thus they |
23324ae1 | 744 | cannot be all removed, @false will be returned |
3c4f71cc VS |
745 | |
746 | ||
747 | ||
748 | ||
749 | ||
4cc4bfaf | 750 | wxPATH_NORM_CASE |
3c4f71cc VS |
751 | |
752 | ||
753 | ||
754 | ||
4cc4bfaf | 755 | if filesystem is case insensitive, transform to lower case |
3c4f71cc VS |
756 | |
757 | ||
758 | ||
759 | ||
760 | ||
4cc4bfaf | 761 | wxPATH_NORM_ABSOLUTE |
3c4f71cc VS |
762 | |
763 | ||
764 | ||
765 | ||
4cc4bfaf | 766 | make the path absolute prepending cwd |
3c4f71cc VS |
767 | |
768 | ||
769 | ||
770 | ||
771 | ||
4cc4bfaf | 772 | wxPATH_NORM_LONG |
3c4f71cc VS |
773 | |
774 | ||
775 | ||
776 | ||
4cc4bfaf | 777 | make the path the long form |
3c4f71cc VS |
778 | |
779 | ||
780 | ||
781 | ||
782 | ||
4cc4bfaf | 783 | wxPATH_NORM_SHORTCUT |
3c4f71cc VS |
784 | |
785 | ||
786 | ||
787 | ||
4cc4bfaf | 788 | resolve if it is a shortcut (Windows only) |
3c4f71cc VS |
789 | |
790 | ||
791 | ||
792 | ||
793 | ||
4cc4bfaf | 794 | wxPATH_NORM_TILDE |
3c4f71cc VS |
795 | |
796 | ||
797 | ||
798 | ||
4cc4bfaf | 799 | replace ~ and ~user (Unix only) |
3c4f71cc VS |
800 | |
801 | ||
802 | ||
803 | ||
804 | ||
4cc4bfaf | 805 | wxPATH_NORM_ALL |
3c4f71cc VS |
806 | |
807 | ||
808 | ||
809 | ||
4cc4bfaf FM |
810 | all of previous flags except wxPATH_NORM_CASE |
811 | @param cwd | |
812 | If not empty, this directory will be used instead of current | |
813 | working directory in normalization (see wxPATH_NORM_ABSOLUTE). | |
7c913512 | 814 | @param format |
4cc4bfaf | 815 | The file name format to use when processing the paths, native by default. |
3c4f71cc | 816 | |
d29a9a8a | 817 | @return @true if normalization was successfully or @false otherwise. |
23324ae1 FM |
818 | */ |
819 | bool Normalize(int flags = wxPATH_NORM_ALL, | |
820 | const wxString& cwd = wxEmptyString, | |
821 | wxPathFormat format = wxPATH_NATIVE); | |
822 | ||
823 | /** | |
824 | These methods allow to work with the file creation, access and modification | |
825 | times. Note that not all filesystems under all platforms implement these times | |
826 | in the same way. For example, the access time under Windows has a resolution of | |
827 | one day (so it is really the access date and not time). The access time may be | |
828 | updated when the file is executed or not depending on the platform. | |
23324ae1 | 829 | GetModificationTime() |
3c4f71cc | 830 | |
23324ae1 | 831 | GetTimes() |
3c4f71cc | 832 | |
23324ae1 | 833 | SetTimes() |
3c4f71cc | 834 | |
23324ae1 | 835 | Touch() |
23324ae1 | 836 | Other file system operations functions are: |
23324ae1 | 837 | Mkdir() |
3c4f71cc | 838 | |
23324ae1 FM |
839 | Rmdir() |
840 | */ | |
841 | ||
842 | ||
843 | /** | |
7c913512 | 844 | Prepends a directory to the file path. Please see |
23324ae1 FM |
845 | AppendDir() for important notes. |
846 | */ | |
847 | void PrependDir(const wxString& dir); | |
848 | ||
849 | /** | |
850 | Removes the specified directory component from the path. | |
3c4f71cc | 851 | |
4cc4bfaf | 852 | @see GetDirCount() |
23324ae1 FM |
853 | */ |
854 | void RemoveDir(size_t pos); | |
855 | ||
856 | /** | |
857 | Removes last directory component from the path. | |
858 | */ | |
859 | void RemoveLastDir(); | |
860 | ||
861 | //@{ | |
862 | /** | |
863 | Deletes the specified directory from the file system. | |
864 | */ | |
865 | bool Rmdir(); | |
7c913512 | 866 | static bool Rmdir(const wxString& dir); |
23324ae1 FM |
867 | //@} |
868 | ||
869 | /** | |
870 | Compares the filename using the rules of this platform. | |
871 | */ | |
872 | bool SameAs(const wxFileName& filepath, | |
328f5751 | 873 | wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
874 | |
875 | //@{ | |
876 | /** | |
877 | Changes the current working directory. | |
878 | */ | |
879 | bool SetCwd(); | |
7c913512 | 880 | static bool SetCwd(const wxString& cwd); |
23324ae1 FM |
881 | //@} |
882 | ||
883 | /** | |
7c913512 FM |
884 | Sets the extension of the file name to be an empty extension. |
885 | This is different from having no extension at all as the file | |
23324ae1 | 886 | name will have a trailing dot after a call to this method. |
3c4f71cc | 887 | |
4cc4bfaf | 888 | @see SetExt(), ClearExt() |
23324ae1 FM |
889 | */ |
890 | void SetEmptyExt(); | |
891 | ||
892 | /** | |
893 | Sets the extension of the file name. Setting an empty string | |
7c913512 FM |
894 | as the extension will remove the extension resulting in a file |
895 | name without a trailing dot, unlike a call to | |
23324ae1 | 896 | SetEmptyExt(). |
3c4f71cc | 897 | |
4cc4bfaf | 898 | @see SetEmptyExt(), ClearExt() |
23324ae1 FM |
899 | */ |
900 | void SetExt(const wxString& ext); | |
901 | ||
902 | /** | |
903 | The full name is the file name and extension (but without the path). | |
904 | */ | |
905 | void SetFullName(const wxString& fullname); | |
906 | ||
907 | /** | |
908 | Sets the name part (without extension). | |
3c4f71cc | 909 | |
4cc4bfaf | 910 | @see SetFullName() |
23324ae1 FM |
911 | */ |
912 | void SetName(const wxString& name); | |
913 | ||
914 | /** | |
915 | Sets the file creation and last access/modification times (any of the pointers | |
916 | may be @NULL). | |
917 | */ | |
918 | bool SetTimes(const wxDateTime* dtAccess, | |
919 | const wxDateTime* dtMod, | |
920 | const wxDateTime* dtCreate); | |
921 | ||
922 | /** | |
923 | Sets the volume specifier. | |
924 | */ | |
925 | void SetVolume(const wxString& volume); | |
926 | ||
927 | //@{ | |
928 | /** | |
929 | This function splits a full file name into components: the volume (with the | |
930 | first version) path (including the volume in the second version), the base name | |
7c913512 | 931 | and the extension. Any of the output parameters (@e volume, @e path, |
4cc4bfaf FM |
932 | @a name or @e ext) may be @NULL if you are not interested in the |
933 | value of a particular component. Also, @a fullpath may be empty on entry. | |
934 | On return, @a path contains the file path (without the trailing separator), | |
935 | @a name contains the file name and @a ext contains the file extension | |
23324ae1 FM |
936 | without leading dot. All three of them may be empty if the corresponding |
937 | component is. The old contents of the strings pointed to by these parameters | |
938 | will be overwritten in any case (if the pointers are not @NULL). | |
cdbcf4c2 | 939 | Note that for a filename "foo." the extension is present, as indicated by the |
7c913512 | 940 | trailing dot, but empty. If you need to cope with such cases, you should use |
4cc4bfaf | 941 | @a hasExt instead of relying on testing whether @a ext is empty or not. |
23324ae1 FM |
942 | */ |
943 | static void SplitPath(const wxString& fullpath, wxString* volume, | |
944 | wxString* path, | |
945 | wxString* name, | |
946 | wxString* ext, | |
4cc4bfaf | 947 | bool hasExt = NULL, |
23324ae1 | 948 | wxPathFormat format = wxPATH_NATIVE); |
7c913512 FM |
949 | static void SplitPath(const wxString& fullpath, |
950 | wxString* volume, | |
951 | wxString* path, | |
952 | wxString* name, | |
953 | wxString* ext, | |
954 | wxPathFormat format = wxPATH_NATIVE); | |
955 | static void SplitPath(const wxString& fullpath, | |
956 | wxString* path, | |
957 | wxString* name, | |
958 | wxString* ext, | |
959 | wxPathFormat format = wxPATH_NATIVE); | |
23324ae1 FM |
960 | //@} |
961 | ||
962 | /** | |
4cc4bfaf | 963 | Splits the given @a fullpath into the volume part (which may be empty) and |
23324ae1 | 964 | the pure path part, not containing any volume. |
3c4f71cc | 965 | |
4cc4bfaf | 966 | @see SplitPath() |
23324ae1 FM |
967 | */ |
968 | static void SplitVolume(const wxString& fullpath, | |
969 | wxString* volume, | |
970 | wxString* path, | |
971 | wxPathFormat format = wxPATH_NATIVE); | |
972 | ||
973 | /** | |
974 | Sets the access and modification times to the current moment. | |
975 | */ | |
976 | bool Touch(); | |
977 | ||
978 | //@{ | |
979 | /** | |
980 | Returns @true if the filenames are different. The string @e filenames | |
981 | is interpreted as a path in the native filename format. | |
982 | */ | |
328f5751 FM |
983 | bool operator operator!=(const wxFileName& filename) const; |
984 | const bool operator operator!=(const wxString& filename) const; | |
23324ae1 FM |
985 | //@} |
986 | ||
987 | //@{ | |
988 | /** | |
989 | Assigns the new value to this filename object. | |
990 | */ | |
991 | wxFileName& operator operator=(const wxFileName& filename); | |
7c913512 | 992 | wxFileName& operator operator=(const wxString& filename); |
23324ae1 FM |
993 | //@} |
994 | ||
995 | //@{ | |
996 | /** | |
997 | Returns @true if the filenames are equal. The string @e filenames is | |
998 | interpreted as a path in the native filename format. | |
999 | */ | |
328f5751 FM |
1000 | bool operator operator==(const wxFileName& filename) const; |
1001 | const bool operator operator==(const wxString& filename) const; | |
23324ae1 FM |
1002 | //@} |
1003 | }; | |
e54c96f1 | 1004 |