]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: wx/filename.h | |
3 | // Purpose: wxFileName - encapsulates a file path | |
4 | // Author: Robert Roebling, Vadim Zeitlin | |
5 | // Modified by: | |
6 | // Created: 28.12.00 | |
7 | // RCS-ID: $Id$ | |
8 | // Copyright: (c) 2000 Robert Roebling | |
9 | // Licence: wxWindows licence | |
10 | ///////////////////////////////////////////////////////////////////////////// | |
11 | ||
12 | #ifndef _WX_FILENAME_H_ | |
13 | #define _WX_FILENAME_H_ | |
14 | ||
15 | /* | |
16 | TODO: | |
17 | ||
18 | 1. support for drives under Windows | |
19 | 2. more file operations: | |
20 | a) chmod() | |
21 | b) [acm]time() - get and set | |
22 | c) file permissions with readable accessors for most common bits | |
23 | such as IsReadable() &c | |
24 | d) rename()? | |
25 | 3. SameFileAs() function to compare inodes under Unix | |
26 | */ | |
27 | ||
28 | #include "wx/arrstr.h" | |
29 | #include "wx/filefn.h" | |
30 | #include "wx/datetime.h" | |
31 | #include "wx/intl.h" | |
32 | ||
33 | #if wxUSE_FILE | |
34 | class WXDLLIMPEXP_BASE wxFile; | |
35 | #endif | |
36 | ||
37 | // ---------------------------------------------------------------------------- | |
38 | // constants | |
39 | // ---------------------------------------------------------------------------- | |
40 | ||
41 | // the various values for the path format: this mainly affects the path | |
42 | // separator but also whether or not the path has the drive part (as under | |
43 | // Windows) | |
44 | enum wxPathFormat | |
45 | { | |
46 | wxPATH_NATIVE = 0, // the path format for the current platform | |
47 | wxPATH_UNIX, | |
48 | wxPATH_BEOS = wxPATH_UNIX, | |
49 | wxPATH_MAC, | |
50 | wxPATH_DOS, | |
51 | wxPATH_WIN = wxPATH_DOS, | |
52 | wxPATH_OS2 = wxPATH_DOS, | |
53 | wxPATH_VMS, | |
54 | ||
55 | wxPATH_MAX // Not a valid value for specifying path format | |
56 | }; | |
57 | ||
58 | // the kind of normalization to do with the file name: these values can be | |
59 | // or'd together to perform several operations at once | |
60 | enum wxPathNormalize | |
61 | { | |
62 | wxPATH_NORM_ENV_VARS = 0x0001, // replace env vars with their values | |
63 | wxPATH_NORM_DOTS = 0x0002, // squeeze all .. and . and prepend cwd | |
64 | wxPATH_NORM_TILDE = 0x0004, // Unix only: replace ~ and ~user | |
65 | wxPATH_NORM_CASE = 0x0008, // if case insensitive => tolower | |
66 | wxPATH_NORM_ABSOLUTE = 0x0010, // make the path absolute | |
67 | wxPATH_NORM_LONG = 0x0020, // make the path the long form | |
68 | wxPATH_NORM_SHORTCUT = 0x0040, // resolve the shortcut, if it is a shortcut | |
69 | wxPATH_NORM_ALL = 0x00ff & ~wxPATH_NORM_CASE | |
70 | }; | |
71 | ||
72 | // what exactly should GetPath() return? | |
73 | enum | |
74 | { | |
75 | wxPATH_GET_VOLUME = 0x0001, // include the volume if applicable | |
76 | wxPATH_GET_SEPARATOR = 0x0002 // terminate the path with the separator | |
77 | }; | |
78 | ||
79 | // MkDir flags | |
80 | enum | |
81 | { | |
82 | wxPATH_MKDIR_FULL = 0x0001 // create directories recursively | |
83 | }; | |
84 | ||
85 | // error code of wxFileName::GetSize() | |
86 | extern wxULongLong wxInvalidSize; | |
87 | ||
88 | ||
89 | // ---------------------------------------------------------------------------- | |
90 | // wxFileName: encapsulates a file path | |
91 | // ---------------------------------------------------------------------------- | |
92 | ||
93 | class WXDLLIMPEXP_BASE wxFileName | |
94 | { | |
95 | public: | |
96 | // constructors and assignment | |
97 | ||
98 | // the usual stuff | |
99 | wxFileName() { Clear(); } | |
100 | wxFileName(const wxFileName& filepath) { Assign(filepath); } | |
101 | ||
102 | // from a full filename: if it terminates with a '/', a directory path | |
103 | // is contructed (the name will be empty), otherwise a file name and | |
104 | // extension are extracted from it | |
105 | wxFileName( const wxString& fullpath, wxPathFormat format = wxPATH_NATIVE ) | |
106 | { Assign( fullpath, format ); } | |
107 | ||
108 | // from a directory name and a file name | |
109 | wxFileName(const wxString& path, | |
110 | const wxString& name, | |
111 | wxPathFormat format = wxPATH_NATIVE) | |
112 | { Assign(path, name, format); } | |
113 | ||
114 | // from a volume, directory name, file base name and extension | |
115 | wxFileName(const wxString& volume, | |
116 | const wxString& path, | |
117 | const wxString& name, | |
118 | const wxString& ext, | |
119 | wxPathFormat format = wxPATH_NATIVE) | |
120 | { Assign(volume, path, name, ext, format); } | |
121 | ||
122 | // from a directory name, file base name and extension | |
123 | wxFileName(const wxString& path, | |
124 | const wxString& name, | |
125 | const wxString& ext, | |
126 | wxPathFormat format = wxPATH_NATIVE) | |
127 | { Assign(path, name, ext, format); } | |
128 | ||
129 | // the same for delayed initialization | |
130 | ||
131 | void Assign(const wxFileName& filepath); | |
132 | ||
133 | void Assign(const wxString& fullpath, | |
134 | wxPathFormat format = wxPATH_NATIVE); | |
135 | ||
136 | void Assign(const wxString& volume, | |
137 | const wxString& path, | |
138 | const wxString& name, | |
139 | const wxString& ext, | |
140 | bool hasExt, | |
141 | wxPathFormat format = wxPATH_NATIVE); | |
142 | ||
143 | void Assign(const wxString& volume, | |
144 | const wxString& path, | |
145 | const wxString& name, | |
146 | const wxString& ext, | |
147 | wxPathFormat format = wxPATH_NATIVE) | |
148 | { Assign(volume, path, name, ext, !ext.empty(), format); } | |
149 | ||
150 | void Assign(const wxString& path, | |
151 | const wxString& name, | |
152 | wxPathFormat format = wxPATH_NATIVE); | |
153 | ||
154 | void Assign(const wxString& path, | |
155 | const wxString& name, | |
156 | const wxString& ext, | |
157 | wxPathFormat format = wxPATH_NATIVE); | |
158 | ||
159 | void AssignDir(const wxString& dir, wxPathFormat format = wxPATH_NATIVE); | |
160 | ||
161 | // assorted assignment operators | |
162 | ||
163 | wxFileName& operator=(const wxFileName& filename) | |
164 | { Assign(filename); return *this; } | |
165 | ||
166 | wxFileName& operator=(const wxString& filename) | |
167 | { Assign(filename); return *this; } | |
168 | ||
169 | // reset all components to default, uninitialized state | |
170 | void Clear(); | |
171 | ||
172 | // static pseudo constructors | |
173 | static wxFileName FileName(const wxString& file, | |
174 | wxPathFormat format = wxPATH_NATIVE); | |
175 | static wxFileName DirName(const wxString& dir, | |
176 | wxPathFormat format = wxPATH_NATIVE); | |
177 | ||
178 | // file tests | |
179 | ||
180 | // is the filename valid at all? | |
181 | bool IsOk() const | |
182 | { | |
183 | // we're fine if we have the path or the name or if we're a root dir | |
184 | return m_dirs.size() != 0 || !m_name.empty() || !m_relative || | |
185 | !m_ext.empty() || m_hasExt; | |
186 | } | |
187 | ||
188 | // does the file with this name exists? | |
189 | bool FileExists() const; | |
190 | static bool FileExists( const wxString &file ); | |
191 | ||
192 | // does the directory with this name exists? | |
193 | bool DirExists() const; | |
194 | static bool DirExists( const wxString &dir ); | |
195 | ||
196 | // VZ: also need: IsDirWritable(), IsFileExecutable() &c (TODO) | |
197 | ||
198 | // time functions | |
199 | #if wxUSE_DATETIME | |
200 | // set the file last access/mod and creation times | |
201 | // (any of the pointers may be NULL) | |
202 | bool SetTimes(const wxDateTime *dtAccess, | |
203 | const wxDateTime *dtMod, | |
204 | const wxDateTime *dtCreate); | |
205 | ||
206 | // set the access and modification times to the current moment | |
207 | bool Touch(); | |
208 | ||
209 | // return the last access, last modification and create times | |
210 | // (any of the pointers may be NULL) | |
211 | bool GetTimes(wxDateTime *dtAccess, | |
212 | wxDateTime *dtMod, | |
213 | wxDateTime *dtCreate) const; | |
214 | ||
215 | // convenience wrapper: get just the last mod time of the file | |
216 | wxDateTime GetModificationTime() const | |
217 | { | |
218 | wxDateTime dtMod; | |
219 | (void)GetTimes(NULL, &dtMod, NULL); | |
220 | return dtMod; | |
221 | } | |
222 | #endif // wxUSE_DATETIME | |
223 | ||
224 | #ifdef __WXMAC__ | |
225 | bool MacSetTypeAndCreator( wxUint32 type , wxUint32 creator ) ; | |
226 | bool MacGetTypeAndCreator( wxUint32 *type , wxUint32 *creator ) ; | |
227 | // gets the 'common' type and creator for a certain extension | |
228 | static bool MacFindDefaultTypeAndCreator( const wxString& ext , wxUint32 *type , wxUint32 *creator ) ; | |
229 | // registers application defined extensions and their default type and creator | |
230 | static void MacRegisterDefaultTypeAndCreator( const wxString& ext , wxUint32 type , wxUint32 creator ) ; | |
231 | // looks up the appropriate type and creator from the registration and then sets | |
232 | bool MacSetDefaultTypeAndCreator() ; | |
233 | #endif | |
234 | ||
235 | // various file/dir operations | |
236 | ||
237 | // retrieve the value of the current working directory | |
238 | void AssignCwd(const wxString& volume = wxEmptyString); | |
239 | static wxString GetCwd(const wxString& volume = wxEmptyString); | |
240 | ||
241 | // change the current working directory | |
242 | bool SetCwd(); | |
243 | static bool SetCwd( const wxString &cwd ); | |
244 | ||
245 | // get the value of user home (Unix only mainly) | |
246 | void AssignHomeDir(); | |
247 | static wxString GetHomeDir(); | |
248 | ||
249 | #if wxUSE_FILE | |
250 | // get a temp file name starting with the specified prefix and open the | |
251 | // file passed to us using this name for writing (atomically if | |
252 | // possible) | |
253 | void AssignTempFileName(const wxString& prefix, wxFile *fileTemp = NULL); | |
254 | static wxString CreateTempFileName(const wxString& prefix, | |
255 | wxFile *fileTemp = NULL); | |
256 | #endif // wxUSE_FILE | |
257 | ||
258 | // directory creation and removal. | |
259 | bool Mkdir( int perm = 0777, int flags = 0); | |
260 | static bool Mkdir( const wxString &dir, int perm = 0777, int flags = 0 ); | |
261 | ||
262 | bool Rmdir(); | |
263 | static bool Rmdir( const wxString &dir ); | |
264 | ||
265 | // operations on the path | |
266 | ||
267 | // normalize the path: with the default flags value, the path will be | |
268 | // made absolute, without any ".." and "." and all environment | |
269 | // variables will be expanded in it | |
270 | // | |
271 | // this may be done using another (than current) value of cwd | |
272 | bool Normalize(int flags = wxPATH_NORM_ALL, | |
273 | const wxString& cwd = wxEmptyString, | |
274 | wxPathFormat format = wxPATH_NATIVE); | |
275 | ||
276 | // get a path path relative to the given base directory, i.e. opposite | |
277 | // of Normalize | |
278 | // | |
279 | // pass an empty string to get a path relative to the working directory | |
280 | // | |
281 | // returns true if the file name was modified, false if we failed to do | |
282 | // anything with it (happens when the file is on a different volume, | |
283 | // for example) | |
284 | bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, | |
285 | wxPathFormat format = wxPATH_NATIVE); | |
286 | ||
287 | // make the path absolute | |
288 | // | |
289 | // this may be done using another (than current) value of cwd | |
290 | bool MakeAbsolute(const wxString& cwd = wxEmptyString, | |
291 | wxPathFormat format = wxPATH_NATIVE) | |
292 | { return Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | | |
293 | wxPATH_NORM_TILDE, cwd, format); } | |
294 | ||
295 | #if defined(__WIN32__) && !defined(__WXWINCE__) && wxUSE_OLE | |
296 | // if the path is a shortcut, return the target and optionally, | |
297 | // the arguments | |
298 | bool GetShortcutTarget(const wxString& shortcutPath, | |
299 | wxString& targetFilename, | |
300 | wxString* arguments = NULL); | |
301 | #endif | |
302 | ||
303 | // Comparison | |
304 | ||
305 | // compares with the rules of the given platforms format | |
306 | bool SameAs(const wxFileName& filepath, | |
307 | wxPathFormat format = wxPATH_NATIVE) const; | |
308 | ||
309 | // compare with another filename object | |
310 | bool operator==(const wxFileName& filename) const | |
311 | { return SameAs(filename); } | |
312 | bool operator!=(const wxFileName& filename) const | |
313 | { return !SameAs(filename); } | |
314 | ||
315 | // compare with a filename string interpreted as a native file name | |
316 | bool operator==(const wxString& filename) const | |
317 | { return SameAs(wxFileName(filename)); } | |
318 | bool operator!=(const wxString& filename) const | |
319 | { return !SameAs(wxFileName(filename)); } | |
320 | ||
321 | // are the file names of this type cases sensitive? | |
322 | static bool IsCaseSensitive( wxPathFormat format = wxPATH_NATIVE ); | |
323 | ||
324 | // is this filename absolute? | |
325 | bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE) const; | |
326 | ||
327 | // is this filename relative? | |
328 | bool IsRelative(wxPathFormat format = wxPATH_NATIVE) const | |
329 | { return !IsAbsolute(format); } | |
330 | ||
331 | // Returns the characters that aren't allowed in filenames | |
332 | // on the specified platform. | |
333 | static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); | |
334 | ||
335 | // Information about path format | |
336 | ||
337 | // get the string separating the volume from the path for this format, | |
338 | // return an empty string if this format doesn't support the notion of | |
339 | // volumes at all | |
340 | static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); | |
341 | ||
342 | // get the string of path separators for this format | |
343 | static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); | |
344 | ||
345 | // get the string of path terminators, i.e. characters which terminate the | |
346 | // path | |
347 | static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); | |
348 | ||
349 | // get the canonical path separator for this format | |
350 | static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE) | |
351 | { return GetPathSeparators(format)[0u]; } | |
352 | ||
353 | // is the char a path separator for this format? | |
354 | static bool IsPathSeparator(wxChar ch, wxPathFormat format = wxPATH_NATIVE); | |
355 | ||
356 | // Dir accessors | |
357 | size_t GetDirCount() const { return m_dirs.size(); } | |
358 | void AppendDir(const wxString& dir); | |
359 | void PrependDir(const wxString& dir); | |
360 | void InsertDir(size_t before, const wxString& dir); | |
361 | void RemoveDir(size_t pos); | |
362 | void RemoveLastDir() { RemoveDir(GetDirCount() - 1); } | |
363 | ||
364 | // Other accessors | |
365 | void SetExt( const wxString &ext ) { m_ext = ext; m_hasExt = !m_ext.empty(); } | |
366 | void ClearExt() { m_ext = wxEmptyString; m_hasExt = false; } | |
367 | void SetEmptyExt() { m_ext = wxT(""); m_hasExt = true; } | |
368 | wxString GetExt() const { return m_ext; } | |
369 | bool HasExt() const { return m_hasExt; } | |
370 | ||
371 | void SetName( const wxString &name ) { m_name = name; } | |
372 | wxString GetName() const { return m_name; } | |
373 | bool HasName() const { return !m_name.empty(); } | |
374 | ||
375 | void SetVolume( const wxString &volume ) { m_volume = volume; } | |
376 | wxString GetVolume() const { return m_volume; } | |
377 | bool HasVolume() const { return !m_volume.empty(); } | |
378 | ||
379 | // full name is the file name + extension (but without the path) | |
380 | void SetFullName(const wxString& fullname); | |
381 | wxString GetFullName() const; | |
382 | ||
383 | const wxArrayString& GetDirs() const { return m_dirs; } | |
384 | ||
385 | // flags are combination of wxPATH_GET_XXX flags | |
386 | wxString GetPath(int flags = wxPATH_GET_VOLUME, | |
387 | wxPathFormat format = wxPATH_NATIVE) const; | |
388 | ||
389 | // Replace current path with this one | |
390 | void SetPath( const wxString &path, wxPathFormat format = wxPATH_NATIVE ); | |
391 | ||
392 | // Construct full path with name and ext | |
393 | wxString GetFullPath( wxPathFormat format = wxPATH_NATIVE ) const; | |
394 | ||
395 | // Return the short form of the path (returns identity on non-Windows platforms) | |
396 | wxString GetShortPath() const; | |
397 | ||
398 | // Return the long form of the path (returns identity on non-Windows platforms) | |
399 | wxString GetLongPath() const; | |
400 | ||
401 | // Is this a file or directory (not necessarily an existing one) | |
402 | bool IsDir() const { return m_name.empty() && m_ext.empty(); } | |
403 | ||
404 | // various helpers | |
405 | ||
406 | // get the canonical path format for this platform | |
407 | static wxPathFormat GetFormat( wxPathFormat format = wxPATH_NATIVE ); | |
408 | ||
409 | // split a fullpath into the volume, path, (base) name and extension | |
410 | // (all of the pointers can be NULL) | |
411 | static void SplitPath(const wxString& fullpath, | |
412 | wxString *volume, | |
413 | wxString *path, | |
414 | wxString *name, | |
415 | wxString *ext, | |
416 | bool *hasExt = NULL, | |
417 | wxPathFormat format = wxPATH_NATIVE); | |
418 | ||
419 | static void SplitPath(const wxString& fullpath, | |
420 | wxString *volume, | |
421 | wxString *path, | |
422 | wxString *name, | |
423 | wxString *ext, | |
424 | wxPathFormat format) | |
425 | { | |
426 | SplitPath(fullpath, volume, path, name, ext, NULL, format); | |
427 | } | |
428 | ||
429 | // compatibility version: volume is part of path | |
430 | static void SplitPath(const wxString& fullpath, | |
431 | wxString *path, | |
432 | wxString *name, | |
433 | wxString *ext, | |
434 | wxPathFormat format = wxPATH_NATIVE); | |
435 | ||
436 | // split a path into volume and pure path part | |
437 | static void SplitVolume(const wxString& fullpathWithVolume, | |
438 | wxString *volume, | |
439 | wxString *path, | |
440 | wxPathFormat format = wxPATH_NATIVE); | |
441 | ||
442 | // Filesize | |
443 | ||
444 | // returns the size of the given filename | |
445 | wxULongLong GetSize() const; | |
446 | static wxULongLong GetSize(const wxString &file); | |
447 | ||
448 | // returns the size in a human readable form | |
449 | wxString GetHumanReadableSize(const wxString &nullsize = wxGetTranslation(_T("Not available")), | |
450 | int precision = 1) const; | |
451 | static wxString GetHumanReadableSize(const wxULongLong &sz, | |
452 | const wxString &nullsize = wxGetTranslation(_T("Not available")), | |
453 | int precision = 1); | |
454 | ||
455 | ||
456 | // deprecated methods, don't use any more | |
457 | // -------------------------------------- | |
458 | ||
459 | #ifndef __DIGITALMARS__ | |
460 | wxString GetPath( bool withSep, wxPathFormat format = wxPATH_NATIVE ) const | |
461 | { return GetPath(withSep ? wxPATH_GET_SEPARATOR : 0, format); } | |
462 | #endif | |
463 | wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE ) const | |
464 | { return GetPath(wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format); } | |
465 | ||
466 | private: | |
467 | // check whether this dir is valid for Append/Prepend/InsertDir() | |
468 | static bool IsValidDirComponent(const wxString& dir); | |
469 | ||
470 | // the drive/volume/device specification (always empty for Unix) | |
471 | wxString m_volume; | |
472 | ||
473 | // the path components of the file | |
474 | wxArrayString m_dirs; | |
475 | ||
476 | // the file name and extension (empty for directories) | |
477 | wxString m_name, | |
478 | m_ext; | |
479 | ||
480 | // when m_dirs is empty it may mean either that we have no path at all or | |
481 | // that our path is '/', i.e. the root directory | |
482 | // | |
483 | // we use m_relative to distinguish between these two cases, it will be | |
484 | // true in the former and false in the latter | |
485 | // | |
486 | // NB: the path is not absolute just because m_relative is false, it still | |
487 | // needs the drive (i.e. volume) in some formats (Windows) | |
488 | bool m_relative; | |
489 | ||
490 | // when m_ext is empty, it may be because we don't have any extension or | |
491 | // because we have an empty extension | |
492 | // | |
493 | // the difference is important as file with name "foo" and without | |
494 | // extension has full name "foo" while with empty extension it is "foo." | |
495 | bool m_hasExt; | |
496 | }; | |
497 | ||
498 | #endif // _WX_FILENAME_H_ | |
499 |