1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxFileName - encapsulates a file path
4 // Author: Robert Roebling, Vadim Zeitlin
8 // Copyright: (c) 2000 Robert Roebling
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_FILENAME_H_
13 #define _WX_FILENAME_H_
15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
16 #pragma interface "filename.h"
20 #include "wx/string.h"
21 #include "wx/arrstr.h"
27 1. support for drives under Windows
28 2. more file operations:
30 b) [acm]time() - get and set
32 d) file permissions with readable accessors for most common bits
33 such as IsReadable() &c
35 3. SameFileAs() function to compare inodes under Unix
38 // ridiculously enough, this will replace DirExists with wxDirExists etc
39 #include "wx/filefn.h"
40 #include "wx/datetime.h"
42 class WXDLLIMPEXP_BASE wxFile
;
44 // ----------------------------------------------------------------------------
46 // ----------------------------------------------------------------------------
48 // the various values for the path format: this mainly affects the path
49 // separator but also whether or not the path has the drive part (as under
53 wxPATH_NATIVE
= 0, // the path format for the current platform
55 wxPATH_BEOS
= wxPATH_UNIX
,
58 wxPATH_WIN
= wxPATH_DOS
,
59 wxPATH_OS2
= wxPATH_DOS
,
62 wxPATH_MAX
// Not a valid value for specifying path format
65 // the kind of normalization to do with the file name: these values can be
66 // or'd together to perform several operations at once
69 wxPATH_NORM_ENV_VARS
= 0x0001, // replace env vars with their values
70 wxPATH_NORM_DOTS
= 0x0002, // squeeze all .. and . and prepend cwd
71 wxPATH_NORM_TILDE
= 0x0004, // Unix only: replace ~ and ~user
72 wxPATH_NORM_CASE
= 0x0008, // if case insensitive => tolower
73 wxPATH_NORM_ABSOLUTE
= 0x0010, // make the path absolute
74 wxPATH_NORM_LONG
= 0x0020, // make the path the long form
75 wxPATH_NORM_SHORTCUT
= 0x0040, // resolve the shortcut, if it is a shortcut
76 wxPATH_NORM_ALL
= 0x00ff & ~wxPATH_NORM_CASE
79 // what exactly should GetPath() return?
82 wxPATH_GET_VOLUME
= 0x0001, // include the volume if applicable
83 wxPATH_GET_SEPARATOR
= 0x0002 // terminate the path with the separator
89 wxPATH_MKDIR_FULL
= 0x0001 // create directories recursively
92 // ----------------------------------------------------------------------------
93 // wxFileName: encapsulates a file path
94 // ----------------------------------------------------------------------------
96 class WXDLLIMPEXP_BASE wxFileName
99 // constructors and assignment
102 wxFileName() { Clear(); }
103 wxFileName(const wxFileName
& filepath
) { Assign(filepath
); }
105 // from a full filename: if it terminates with a '/', a directory path
106 // is contructed (the name will be empty), otherwise a file name and
107 // extension are extracted from it
108 wxFileName( const wxString
& fullpath
, wxPathFormat format
= wxPATH_NATIVE
)
109 { Assign( fullpath
, format
); }
111 // from a directory name and a file name
112 wxFileName(const wxString
& path
,
113 const wxString
& name
,
114 wxPathFormat format
= wxPATH_NATIVE
)
115 { Assign(path
, name
, format
); }
117 // from a volume, directory name, file base name and extension
118 wxFileName(const wxString
& volume
,
119 const wxString
& path
,
120 const wxString
& name
,
122 wxPathFormat format
= wxPATH_NATIVE
)
123 { Assign(volume
, path
, name
, ext
, format
); }
125 // from a directory name, file base name and extension
126 wxFileName(const wxString
& path
,
127 const wxString
& name
,
129 wxPathFormat format
= wxPATH_NATIVE
)
130 { Assign(path
, name
, ext
, format
); }
132 // the same for delayed initialization
134 void Assign(const wxFileName
& filepath
);
136 void Assign(const wxString
& fullpath
,
137 wxPathFormat format
= wxPATH_NATIVE
);
139 void Assign(const wxString
& volume
,
140 const wxString
& path
,
141 const wxString
& name
,
143 wxPathFormat format
= wxPATH_NATIVE
);
145 void Assign(const wxString
& path
,
146 const wxString
& name
,
147 wxPathFormat format
= wxPATH_NATIVE
);
149 void Assign(const wxString
& path
,
150 const wxString
& name
,
152 wxPathFormat format
= wxPATH_NATIVE
)
155 Assign(wxEmptyString
, path
, name
, ext
, format
);
158 void AssignDir(const wxString
& dir
, wxPathFormat format
= wxPATH_NATIVE
);
160 // assorted assignment operators
162 wxFileName
& operator=(const wxFileName
& filename
)
163 { Assign(filename
); return *this; }
165 wxFileName
& operator=(const wxString
& filename
)
166 { Assign(filename
); return *this; }
168 // reset all components to default, uninitialized state
171 // static pseudo constructors
172 static wxFileName
FileName(const wxString
& file
,
173 wxPathFormat format
= wxPATH_NATIVE
);
174 static wxFileName
DirName(const wxString
& dir
,
175 wxPathFormat format
= wxPATH_NATIVE
);
179 // is the filename valid at all?
180 bool IsOk() const { return m_dirs
.size() != 0 || !m_name
.IsEmpty(); }
182 // does the file with this name exists?
183 bool FileExists() const;
184 static bool FileExists( const wxString
&file
);
186 // does the directory with this name exists?
187 bool DirExists() const;
188 static bool DirExists( const wxString
&dir
);
190 // VZ: also need: IsDirWritable(), IsFileExecutable() &c (TODO)
194 // set the file last access/mod and creation times
195 // (any of the pointers may be NULL)
196 bool SetTimes(const wxDateTime
*dtAccess
,
197 const wxDateTime
*dtMod
,
198 const wxDateTime
*dtCreate
);
200 // set the access and modification times to the current moment
203 // return the last access, last modification and create times
204 // (any of the pointers may be NULL)
205 bool GetTimes(wxDateTime
*dtAccess
,
207 wxDateTime
*dtCreate
) const;
209 // convenience wrapper: get just the last mod time of the file
210 wxDateTime
GetModificationTime() const
213 (void)GetTimes(NULL
, &dtMod
, NULL
);
216 #endif // wxUSE_DATETIME
219 bool MacSetTypeAndCreator( wxUint32 type
, wxUint32 creator
) ;
220 bool MacGetTypeAndCreator( wxUint32
*type
, wxUint32
*creator
) ;
221 // gets the 'common' type and creator for a certain extension
222 static bool MacFindDefaultTypeAndCreator( const wxString
& ext
, wxUint32
*type
, wxUint32
*creator
) ;
223 // registers application defined extensions and their default type and creator
224 static void MacRegisterDefaultTypeAndCreator( const wxString
& ext
, wxUint32 type
, wxUint32 creator
) ;
225 // looks up the appropriate type and creator from the registration and then sets
226 bool MacSetDefaultTypeAndCreator() ;
229 // various file/dir operations
231 // retrieve the value of the current working directory
232 void AssignCwd(const wxString
& volume
= wxEmptyString
);
233 static wxString
GetCwd(const wxString
& volume
= wxEmptyString
);
235 // change the current working directory
237 static bool SetCwd( const wxString
&cwd
);
239 // get the value of user home (Unix only mainly)
240 void AssignHomeDir();
241 static wxString
GetHomeDir();
243 // get a temp file name starting with the specified prefix and open the
244 // file passed to us using this name for writing (atomically if
246 void AssignTempFileName(const wxString
& prefix
, wxFile
*fileTemp
= NULL
);
247 static wxString
CreateTempFileName(const wxString
& prefix
,
248 wxFile
*fileTemp
= NULL
);
250 // directory creation and removal.
251 bool Mkdir( int perm
= 0777, int flags
= 0);
252 static bool Mkdir( const wxString
&dir
, int perm
= 0777, int flags
= 0 );
255 static bool Rmdir( const wxString
&dir
);
257 // operations on the path
259 // normalize the path: with the default flags value, the path will be
260 // made absolute, without any ".." and "." and all environment
261 // variables will be expanded in it
263 // this may be done using another (than current) value of cwd
264 bool Normalize(int flags
= wxPATH_NORM_ALL
,
265 const wxString
& cwd
= wxEmptyString
,
266 wxPathFormat format
= wxPATH_NATIVE
);
268 // get a path path relative to the given base directory, i.e. opposite
271 // pass an empty string to get a path relative to the working directory
273 // returns true if the file name was modified, false if we failed to do
274 // anything with it (happens when the file is on a different volume,
276 bool MakeRelativeTo(const wxString
& pathBase
= wxEmptyString
,
277 wxPathFormat format
= wxPATH_NATIVE
);
279 // make the path absolute
281 // this may be done using another (than current) value of cwd
282 bool MakeAbsolute(const wxString
& cwd
= wxEmptyString
,
283 wxPathFormat format
= wxPATH_NATIVE
)
284 { return Normalize(wxPATH_NORM_DOTS
| wxPATH_NORM_ABSOLUTE
|
285 wxPATH_NORM_TILDE
, cwd
, format
); }
287 #if defined(__WIN32__) && !defined(__WXWINCE__) && wxUSE_OLE
288 // if the path is a shortcut, return the target and optionally,
290 bool GetShortcutTarget(const wxString
& shortcutPath
,
291 wxString
& targetFilename
,
292 wxString
* arguments
= NULL
);
297 // compares with the rules of the given platforms format
298 bool SameAs(const wxFileName
& filepath
,
299 wxPathFormat format
= wxPATH_NATIVE
) const;
301 // compare with another filename object
302 bool operator==(const wxFileName
& filename
) const
303 { return SameAs(filename
); }
304 bool operator!=(const wxFileName
& filename
) const
305 { return !SameAs(filename
); }
307 // compare with a filename string interpreted as a native file name
308 bool operator==(const wxString
& filename
) const
309 { return SameAs(wxFileName(filename
)); }
310 bool operator!=(const wxString
& filename
) const
311 { return !SameAs(wxFileName(filename
)); }
313 // are the file names of this type cases sensitive?
314 static bool IsCaseSensitive( wxPathFormat format
= wxPATH_NATIVE
);
316 // is this filename absolute?
317 bool IsAbsolute(wxPathFormat format
= wxPATH_NATIVE
) const;
319 // is this filename relative?
320 bool IsRelative(wxPathFormat format
= wxPATH_NATIVE
) const
321 { return !IsAbsolute(format
); }
323 // Returns the characters that aren't allowed in filenames
324 // on the specified platform.
325 static wxString
GetForbiddenChars(wxPathFormat format
= wxPATH_NATIVE
);
327 // Information about path format
329 // get the string separating the volume from the path for this format,
330 // return an empty string if this format doesn't support the notion of
332 static wxString
GetVolumeSeparator(wxPathFormat format
= wxPATH_NATIVE
);
334 // get the string of path separators for this format
335 static wxString
GetPathSeparators(wxPathFormat format
= wxPATH_NATIVE
);
337 // get the canonical path separator for this format
338 static wxChar
GetPathSeparator(wxPathFormat format
= wxPATH_NATIVE
)
339 { return GetPathSeparators(format
)[0u]; }
341 // is the char a path separator for this format?
342 static bool IsPathSeparator(wxChar ch
, wxPathFormat format
= wxPATH_NATIVE
);
345 void AppendDir( const wxString
&dir
);
346 void PrependDir( const wxString
&dir
);
347 void InsertDir( int before
, const wxString
&dir
);
348 void RemoveDir( int pos
);
349 size_t GetDirCount() const { return m_dirs
.size(); }
352 void SetExt( const wxString
&ext
) { m_ext
= ext
; }
353 wxString
GetExt() const { return m_ext
; }
354 bool HasExt() const { return !m_ext
.empty(); }
356 void SetName( const wxString
&name
) { m_name
= name
; }
357 wxString
GetName() const { return m_name
; }
358 bool HasName() const { return !m_name
.empty(); }
360 void SetVolume( const wxString
&volume
) { m_volume
= volume
; }
361 wxString
GetVolume() const { return m_volume
; }
362 bool HasVolume() const { return !m_volume
.empty(); }
364 // full name is the file name + extension (but without the path)
365 void SetFullName(const wxString
& fullname
);
366 wxString
GetFullName() const;
368 const wxArrayString
& GetDirs() const { return m_dirs
; }
370 // flags are combination of wxPATH_GET_XXX flags
371 wxString
GetPath(int flags
= wxPATH_GET_VOLUME
,
372 wxPathFormat format
= wxPATH_NATIVE
) const;
374 // Replace current path with this one
375 void SetPath( const wxString
&path
, wxPathFormat format
= wxPATH_NATIVE
);
377 // Construct full path with name and ext
378 wxString
GetFullPath( wxPathFormat format
= wxPATH_NATIVE
) const;
380 // Return the short form of the path (returns identity on non-Windows platforms)
381 wxString
GetShortPath() const;
383 // Return the long form of the path (returns identity on non-Windows platforms)
384 wxString
GetLongPath() const;
386 // Is this a file or directory (not necessarily an existing one)
387 bool IsDir() const { return m_name
.empty() && m_ext
.empty(); }
391 // get the canonical path format for this platform
392 static wxPathFormat
GetFormat( wxPathFormat format
= wxPATH_NATIVE
);
394 // split a fullpath into the volume, path, (base) name and extension
395 // (all of the pointers can be NULL)
396 static void SplitPath(const wxString
& fullpath
,
401 wxPathFormat format
= wxPATH_NATIVE
);
403 // compatibility version
404 static void SplitPath(const wxString
& fullpath
,
408 wxPathFormat format
= wxPATH_NATIVE
);
411 // deprecated methods, don't use any more
412 // --------------------------------------
414 #ifndef __DIGITALMARS__
415 wxString
GetPath( bool withSep
, wxPathFormat format
= wxPATH_NATIVE
) const
416 { return GetPath(withSep
? wxPATH_GET_SEPARATOR
: 0, format
); }
418 wxString
GetPathWithSep(wxPathFormat format
= wxPATH_NATIVE
) const
419 { return GetPath(wxPATH_GET_SEPARATOR
, format
); }
422 // check whether this dir is valid for Append/Prepend/InsertDir()
423 static bool IsValidDirComponent(const wxString
& dir
);
425 // the drive/volume/device specification (always empty for Unix)
428 // the path components of the file
429 wxArrayString m_dirs
;
431 // the file name and extension (empty for directories)
435 // when m_dirs is empty it may mean either that we have no path at all or
436 // that our path is '/', i.e. the root directory
438 // we use m_relative to distinguish between these two cases, it will be
439 // true in the former and false in the latter
441 // NB: the path is not absolute just because m_relative is false, it still
442 // needs the drive (i.e. volume) in some formats (Windows)
446 #endif // _WX_FILENAME_H_