1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxFileName documentation
4 %% Author: Vadim Zeitlin
8 %% Copyright: (c) 2001 Vadim Zeitlin
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxFileName
}}\label{wxfilename
}
14 wxFileName encapsulates a file name. This class serves two purposes: first, it
15 provides the functions to split the file names into components and to recombine
16 these components in the full file name which can then be passed to the OS file
17 functions (and
\helpref{wxWindows functions
}{filefunctions
} wrapping them).
18 Second, it includes the functions for working with the files itself. Note that
19 to change the file data you should use
\helpref{wxFile
}{wxfile
} class instead,
20 wxFileName provides functions for working with the file attributes.
22 \wxheading{Derived from
}
26 \wxheading{Data structures
}
28 Many wxFileName methods accept the path format argument which is by
\rtfsp
29 {\tt wxPATH
\_NATIVE} by default meaning to use the path format native for the
32 The path format affects the operation of wxFileName functions in several ways:
33 first and foremost, it defines the path separator character to use, but it also
34 affects other things such as whether the path has the drive part or not.
39 wxPATH_NATIVE =
0, // the path format for the current platform
45 wxPATH_BEOS = wxPATH_UNIX,
46 wxPATH_WIN = wxPATH_DOS,
47 wxPATH_OS2 = wxPATH_DOS
51 The kind of normalization to do with the file name: these values can be
52 or'd together to perform several operations at once in
\rtfsp
53 \helpref{Normalize
}{wxfilenamenormalize
}.
58 wxPATH_NORM_ENV_VARS =
0x0001, // replace env vars with their values
59 wxPATH_NORM_DOTS =
0x0002, // squeeze all .. and . and prepend cwd
60 wxPATH_NORM_TILDE =
0x0004, // Unix only: replace ~ and ~user
61 wxPATH_NORM_CASE =
0x0008, // if case insensitive => tolower
62 wxPATH_NORM_ABSOLUTE =
0x0010, // make the path absolute
63 wxPATH_NORM_LONG =
0x0020, // make the path the long form
64 wxPATH_NORM_ALL =
0x003f
68 \latexignore{\rtfignore{\wxheading{Function groups
}}}
70 \membersection{File name format
}
72 wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
73 and VMS formats. Although these formats are quite different, wxFileName tries
74 to treat them all in the sam generic way. It supposes that all file names
75 consist of the following parts: the volume (also known as drive under Windows
76 or device under VMS), the path which is a sequence of directory names separated
77 by the
\helpref{path separators
}{wxfilenamegetpathseparators
} and the full
78 filename itself which, in turn, is composed from the base file name and the
79 extension. All of the individual components of the file name may be empty and,
80 for example, the volume name is always empty under Unix, but if they are all
81 empty simultaneously, the filename object is considered to be in an invalid
82 state and
\helpref{IsOk
}{wxfilenameisok
} returns
{\tt FALSE
} for it.
84 File names can be case-sensitive or not, the function
\rtfsp
85 \helpref{IsCaseSensitive
}{wxfilenameiscasesensitive
} allows to determine this.
87 The rules for determining if the file name is absolute or relative also depends
88 on the file name format and the only portable way to answer to this question is
89 to use
\helpref{IsAbsolute
}{wxfilenameisabsolute
} method. To ensure that the
90 filename is absolute you may use
\helpref{Normalize
}{wxfilenamenormalize
}.
92 Other functions returning information about the file format provided by this
93 class are
\helpref{GetVolumeSeparator
}{wxfilenamegetvolumeseparator
},
\rtfsp
94 \helpref{IsPathSeparator
}{wxfilenameispathseparator
} and
\rtfsp
95 \helpref{IsWild
}{wxfilenameiswild
}.
97 \helpref{IsRelative
}{wxfilenameisrelative
}
99 \membersection{File name construction
}
103 \membersection{File tests
}
105 Before doing the other tests you should use
\helpref{IsOk
}{wxfilenameisok
} to
106 verify that the filename is well defined. If it is,
107 \helpref{FileExists
}{wxfilenamefileexists
} can be used to test if a file with
108 such name exists and
\helpref{DirExists
}{wxfilenamedirexists
} - if a directory
109 with this name exists.
111 File names should be compared using
\helpref{SameAs
}{wxfilenamesameas
} method
112 or
\helpref{$==$
}{wxfilenameoperatorequal
}.
114 \membersection{File name components
}
116 These functions allow to examine and modify the directories of the path:
118 \helpref{AppendDir
}{wxfilenameappenddir
}\\
119 \helpref{InsertDir
}{wxfilenameinsertdir
}\\
120 \helpref{GetDirCount
}{wxfilenamegetdircount
}
121 \helpref{PrependDir
}{wxfilenameprependdir
}\\
122 \helpref{RemoveDir
}{wxfilenameremovedir
}
124 To change the components of the file name individually you can use the
127 \helpref{GetExt
}{wxfilenamegetext
}\\
128 \helpref{GetName
}{wxfilenamegetname
}\\
129 \helpref{GetVolume
}{wxfilenamegetvolume
}\\
130 \helpref{HasExt
}{wxfilenamehasext
}\\
131 \helpref{HasName
}{wxfilenamehasname
}\\
132 \helpref{HasVolume
}{wxfilenamehasvolume
}\\
133 \helpref{SetExt
}{wxfilenamesetext
}\\
134 \helpref{SetName
}{wxfilenamesetname
}\\
135 \helpref{SetVolume
}{wxfilenamesetvolume
}\\
137 \membersection{Operations
}
139 These methods allow to work with the file creation, access and modification
142 \helpref{GetModificationTime
}{wxfilenamegetmodificationtime
}\\
143 \helpref{GetTimes
}{wxfilenamegettimes
}\\
144 \helpref{SetTimes
}{wxfilenamesettimes
}\\
145 \helpref{Touch
}{wxfilenametouch
}
147 Other file system operations functions are:
149 \helpref{Mkdir
}{wxfilenamemkdir
}\\
150 \helpref{Rmdir
}{wxfilenamermdir
}
152 \latexignore{\rtfignore{\wxheading{Members
}}}
154 \membersection{wxFileName::wxFileName
}\label{wxfilenamewxfilename
}
156 \func{}{wxFileName
}{\void}
160 \func{}{wxFileName
}{\param{const wxFileName\&
}{filename
}}
164 \func{}{wxFileName
}{\param{const wxString\&
}{fullpath
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
166 From a full filename: if it terminates with a '/', a directory path
167 is contructed (the name will be empty), otherwise a file name and
168 extension are extracted from it
170 \func{}{wxFileName
}{\param{const wxString\&
}{path
},
\param{const wxString\&
}{name
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
172 Constructor from a directory name and a file name.
174 \func{}{wxFileName
}{\param{const wxString\&
}{path
},
\param{const wxString\&
}{name
},
\param{const wxString\&
}{ext
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
176 Constructor from a directory name, file base name and extension
178 \membersection{wxFileName::AppendDir
}\label{wxfilenameappenddir
}
180 \func{void
}{AppendDir
}{\param{const wxString\&
}{dir
}}
183 \membersection{wxFileName::Assign
}\label{wxfilenameassign
}
185 \func{void
}{Assign
}{\param{const wxFileName\&
}{filepath
}}
188 \membersection{wxFileName::Assign
}\label{wxfilenameassign
}
190 \func{void
}{Assign
}{\param{const wxString\&
}{fullpath
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
193 \membersection{wxFileName::Assign
}\label{wxfilenameassign
}
195 \func{void
}{Assign
}{\param{const wxString\&
}{volume
},
\param{const wxString\&
}{path
},
\param{const wxString\&
}{name
},
\param{const wxString\&
}{ext
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
198 \membersection{wxFileName::Assign
}\label{wxfilenameassign
}
200 \func{void
}{Assign
}{\param{const wxString\&
}{path
},
\param{const wxString\&
}{name
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
203 \membersection{wxFileName::Assign
}\label{wxfilenameassign
}
205 \func{void
}{Assign
}{\param{const wxString\&
}{path
},
\param{const wxString\&
}{name
},
\param{const wxString\&
}{ext
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
208 \membersection{wxFileName::AssignCwd
}\label{wxfilenameassigncwd
}
210 \func{void
}{AssignCwd
}{\param{const wxString\&
}{volume = ""
}}
212 Makes this object refer to the current working directory on the specified
213 volume (or current volume if
{\it volume
} is empty).
217 \helpref{GetCwd
}{wxfilenamegetcwd
}
219 \membersection{wxFileName::AssignDir
}\label{wxfilenameassigndir
}
221 \func{void
}{AssignDir
}{\param{const wxString\&
}{dir
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
226 \membersection{wxFileName::AssignHomeDir
}\label{wxfilenameassignhomedir
}
228 \func{void
}{AssignHomeDir
}{\void}
230 get the value of user home (Unix only mainly)
233 \membersection{wxFileName::AssignTempFileName
}\label{wxfilenameassigntempfilename
}
235 \func{void
}{AssignTempFileName
}{\param{const wxString\&
}{prefix
}}
237 The function calls
\helpref{CreateTempFileName
}{wxfilenamecreatetempfilename
} to
238 create a temporary file and sets this object to the name of the file. If a
239 temporary file couldn't be created, the object is put into the
\rtfsp
240 \helpref{invalid
}{wxfilenameisok
} state.
242 \membersection{wxFileName::Clear
}\label{wxfilenameclear
}
244 \func{void
}{Clear
}{\void}
246 Reset all components to default, uninitialized state.
248 \membersection{wxFileName::CreateTempFileName
}{wxfilenamecreatetempfilename
}
250 \func{static wxString
}{CreateTempFileName
}{\param{const wxString\&
}{prefix
}}
252 Returns a temporary file name starting with the given
{\it prefix
}. If
253 the
{\it prefix
} is an absolute path, the temporary file is created in this
254 directory, otherwise it is created in the default system directory for the
255 temporary files or in the current directory.
257 If the function succeeds, the temporary file is actually created (but not
258 opened) as well. Under Unix, it will have read and write permissions for the
261 \wxheading{Return value
}
263 The full temporary file name or an empty string on error.
265 \membersection{wxFileName::DirExists
}\label{wxfilenamedirexists
}
267 \func{bool
}{DirExists
}{\void}
269 does the directory with this name exists?
272 \membersection{wxFileName::DirExists
}\label{wxfilenamedirexists
}
274 \func{bool
}{DirExists
}{\param{const wxString\&
}{dir
}}
277 \membersection{wxFileName::DirName
}\label{wxfilenamedirname
}
279 \func{wxFileName
}{DirName
}{\param{const wxString\&
}{dir
}}
282 \membersection{wxFileName::FileExists
}\label{wxfilenamefileexists
}
284 \func{bool
}{FileExists
}{\void}
286 does the file with this name exists?
289 \membersection{wxFileName::FileExists
}\label{wxfilenamefileexists
}
291 \func{bool
}{FileExists
}{\param{const wxString\&
}{file
}}
294 \membersection{wxFileName::FileName
}\label{wxfilenamefilename
}
296 \func{wxFileName
}{FileName
}{\param{const wxString\&
}{file
}}
298 static pseudo constructors
301 \membersection{wxFileName::GetCwd
}\label{wxfilenamegetcwd
}
303 \func{wxString
}{GetCwd
}{\param{const wxString\&
}{volume = ""
}}
305 Retrieve the value of the current working directory on the specified volume. If
306 the volume is empty, the programs current working directory is returned for the
309 \wxheading{Return value
}
311 The string containing the current working directory or an empty string on
316 \helpref{AssignCwd
}{wxfilenameassigncwd
}
318 \membersection{wxFileName::GetDirCount
}\label{wxfilenamegetdircount
}
320 \constfunc{size
\_t}{GetDirCount
}{\void}
323 \membersection{wxFileName::GetDirs
}\label{wxfilenamegetdirs
}
325 \constfunc{const wxArrayString\&
}{GetDirs
}{\void}
328 \membersection{wxFileName::GetExt
}\label{wxfilenamegetext
}
330 \constfunc{wxString
}{GetExt
}{\void}
333 \membersection{wxFileName::GetFormat
}\label{wxfilenamegetformat
}
335 \func{wxPathFormat
}{GetFormat
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
338 get the canonical path format for this platform
341 \membersection{wxFileName::GetFullName
}\label{wxfilenamegetfullname
}
343 \constfunc{wxString
}{GetFullName
}{\void}
346 \membersection{wxFileName::GetFullPath
}\label{wxfilenamegetfullpath
}
348 \constfunc{wxString
}{GetFullPath
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
350 add separator Construct full path with name and ext
353 \membersection{wxFileName::GetHomeDir
}\label{wxfilenamegethomedir
}
355 \func{wxString
}{GetHomeDir
}{\void}
358 \membersection{wxFileName::GetLongPath
}\label{wxfilenamegetlongpath
}
360 \constfunc{wxString
}{GetLongPath
}{\void}
362 Return the long form of the path (returns identity on non-Windows platforms)
365 \membersection{wxFileName::GetModificationTime
}\label{wxfilenamegetmodificationtime
}
367 \constfunc{wxDateTime
}{GetModificationTime
}{\void}
369 convenience wrapper: get just the last mod time of the file
372 \membersection{wxFileName::GetName
}\label{wxfilenamegetname
}
374 \constfunc{wxString
}{GetName
}{\void}
377 \membersection{wxFileName::GetPath
}\label{wxfilenamegetpath
}
379 \constfunc{wxString
}{GetPath
}{\param{bool
}{add
\_separator = FALSE
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
381 Construct path only - possibly with the trailing separator
384 \membersection{wxFileName::GetPathSeparators
}\label{wxfilenamegetpathseparators
}
386 \func{wxString
}{GetPathSeparators
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
388 get the string of path separators for this format
391 \membersection{wxFileName::GetPathWithSep
}\label{wxfilenamegetpathwithsep
}
393 \constfunc{wxString
}{GetPathWithSep
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
395 more readable synonym
398 \membersection{wxFileName::GetShortPath
}\label{wxfilenamegetshortpath
}
400 \constfunc{wxString
}{GetShortPath
}{\void}
402 Return the short form of the path (returns identity on non-Windows platforms)
405 \membersection{wxFileName::GetTimes
}\label{wxfilenamegettimes
}
407 \constfunc{bool
}{GetTimes
}{\param{wxDateTime*
}{dtAccess
},
\param{wxDateTime*
}{dtMod
},
\param{wxDateTime*
}{dtChange
}}
409 return the last access, last modification and last change times
410 (any of the pointers may be NULL)
413 \membersection{wxFileName::GetVolume
}\label{wxfilenamegetvolume
}
415 \constfunc{wxString
}{GetVolume
}{\void}
418 \membersection{wxFileName::GetVolumeSeparator
}\label{wxfilenamegetvolumeseparator
}
420 \func{wxString
}{GetVolumeSeparator
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
422 get the string separating the volume from the path for this format
425 \membersection{wxFileName::HasExt
}\label{wxfilenamehasext
}
427 \constfunc{bool
}{HasExt
}{\void}
430 \membersection{wxFileName::HasName
}\label{wxfilenamehasname
}
432 \constfunc{bool
}{HasName
}{\void}
435 \membersection{wxFileName::HasVolume
}\label{wxfilenamehasvolume
}
437 \constfunc{bool
}{HasVolume
}{\void}
440 \membersection{wxFileName::InsertDir
}\label{wxfilenameinsertdir
}
442 \func{void
}{InsertDir
}{\param{int
}{before
},
\param{const wxString\&
}{dir
}}
445 \membersection{wxFileName::IsAbsolute
}\label{wxfilenameisabsolute
}
447 \func{bool
}{IsAbsolute
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
449 is this filename absolute?
452 \membersection{wxFileName::IsCaseSensitive
}\label{wxfilenameiscasesensitive
}
454 \func{bool
}{IsCaseSensitive
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
457 are the file names of this type cases sensitive?
460 \membersection{wxFileName::IsOk
}\label{wxfilenameisok
}
462 \constfunc{bool
}{IsOk
}{\void}
464 Returns
{\tt TRUE
} if the filename is valid,
{\tt FALSE
} if it is not
465 initialized yet. The assignment functions and
466 \helpref{Clear
}{wxfilenameclear
} may reset the object to the uninitialized,
467 invalid state (the former only do it on failure).
469 \membersection{wxFileName::IsPathSeparator
}\label{wxfilenameispathseparator
}
471 \func{bool
}{IsPathSeparator
}{\param{wxChar
}{ch
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
473 is the char a path separator for this format?
476 \membersection{wxFileName::IsRelative
}\label{wxfilenameisrelative
}
478 \func{bool
}{IsRelative
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
480 is this filename relative?
483 \membersection{wxFileName::IsWild
}\label{wxfilenameiswild
}
485 \func{bool
}{IsWild
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
487 FIXME: what exactly does this do?
490 \membersection{wxFileName::Mkdir
}\label{wxfilenamemkdir
}
492 \func{bool
}{Mkdir
}{\param{int
}{perm =
0777},
\param{bool
}{full = FALSE
}}
494 \func{static bool
}{Mkdir
}{\param{const wxString\&
}{dir
},
\param{int
}{perm =
0777},
\param{bool
}{full = FALSE
}}
496 \docparam{dir
}{the directory to create
}
498 \docparam{parm
}{the permissions for the newly created directory
}
500 \docparam{full
}{if
{\tt TRUE
}, will try to make each directory in the path
}
502 \wxheading{Return value
}
504 Returns
{\tt TRUE
} if the directory was successfully created,
{\tt FALSE
}
507 \membersection{wxFileName::Normalize
}\label{wxfilenamenormalize
}
509 \func{bool
}{Normalize
}{\param{wxPathNormalize
}{flags = wxPATH
\_NORM\_ALL},
\param{const wxString\&
}{cwd = wxEmptyString
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
511 operations on the path
512 normalize the path: with the default flags value, the path will be
513 made absolute, without any ".." and "." and all environment
514 variables will be expanded in it
515 this may be done using another (than current) value of cwd
518 \membersection{wxFileName::PrependDir
}\label{wxfilenameprependdir
}
520 \func{void
}{PrependDir
}{\param{const wxString\&
}{dir
}}
523 \membersection{wxFileName::RemoveDir
}\label{wxfilenameremovedir
}
525 \func{void
}{RemoveDir
}{\param{int
}{pos
}}
528 \membersection{wxFileName::Rmdir
}\label{wxfilenamermdir
}
530 \func{bool
}{Rmdir
}{\void}
532 \func{static bool
}{Rmdir
}{\param{const wxString\&
}{dir
}}
534 Deletes the specified directory.
537 \membersection{wxFileName::SameAs
}\label{wxfilenamesameas
}
539 \func{bool
}{SameAs
}{\param{const wxFileName\&
}{filepath
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
541 Compares the filename using the rules of this platform
544 \membersection{wxFileName::SetCwd
}\label{wxfilenamesetcwd
}
546 \func{bool
}{SetCwd
}{\void}
548 \func{static bool
}{SetCwd
}{\param{const wxString\&
}{cwd
}}
550 change the current working directory
552 \membersection{wxFileName::SetExt
}\label{wxfilenamesetext
}
554 \func{void
}{SetExt
}{\param{const wxString\&
}{ext
}}
557 \membersection{wxFileName::SetFullName
}\label{wxfilenamesetfullname
}
559 \func{void
}{SetFullName
}{\param{const wxString\&
}{fullname
}}
561 full name is the file name + extension (but without the path)
564 \membersection{wxFileName::SetName
}\label{wxfilenamesetname
}
566 \func{void
}{SetName
}{\param{const wxString\&
}{name
}}
569 \membersection{wxFileName::SetTimes
}\label{wxfilenamesettimes
}
571 \func{bool
}{SetTimes
}{\param{const wxDateTime*
}{dtCreate
},
\param{const wxDateTime*
}{dtAccess
},
\param{const wxDateTime*
}{dtMod
}}
573 set the file creation and last access/mod times
574 (any of the pointers may be NULL)
577 \membersection{wxFileName::SetVolume
}\label{wxfilenamesetvolume
}
579 \func{void
}{SetVolume
}{\param{const wxString\&
}{volume
}}
582 \membersection{wxFileName::SplitPath
}\label{wxfilenamesplitpath
}
584 \func{void
}{SplitPath
}{\param{const wxString\&
}{fullpath
},
\param{wxString*
}{volume
},
\param{wxString*
}{path
},
\param{wxString*
}{name
},
\param{wxString*
}{ext
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
586 \func{void
}{SplitPath
}{\param{const wxString\&
}{fullpath
},
\param{wxString*
}{path
},
\param{wxString*
}{name
},
\param{wxString*
}{ext
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
588 split a fullpath into the volume, path, (base) name and extension
589 (all of the pointers can be NULL)
591 \membersection{wxFileName::Touch
}\label{wxfilenametouch
}
593 \func{bool
}{Touch
}{\void}
595 set the access and modification times to the current moment
598 \membersection{wxFileName::operator=
}\label{wxfilenameoperatorassign
}
600 \func{wxFileName\& operator
}{operator=
}{\param{const wxFileName\&
}{filename
}}
602 \func{wxFileName\& operator
}{operator=
}{\param{const wxString\&
}{filename
}}
604 Assigns the new value to this filename object.
606 \membersection{wxFileName::operator==
}\label{wxfilenameoperatorequal
}
608 \func{bool operator
}{operator==
}{\param{const wxFileName\&
}{filename
}}
610 \func{bool operator
}{operator==
}{\param{const wxString\&
}{filename
}}
612 Returns
{\tt TRUE
} if the filenames are equal for the native file format.