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