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