Added wxBUFFER_VIRTUAL_AREA, wxBUFFER_CLIENT_AREA to buffered DC
[wxWidgets.git] / docs / latex / wx / filename.tex
0 / 859 (  0%)
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
22\wxheading{Derived from}
23
24No base class
25
26\wxheading{Include files}
27
28<wx/filename.h>
29
30\wxheading{Data structures}
31
32Many wxFileName methods accept the path format argument which is by\rtfsp
33{\tt wxPATH\_NATIVE} by default meaning to use the path format native for the
34current platform.
35
36The path format affects the operation of wxFileName functions in several ways:
37first and foremost, it defines the path separator character to use, but it also
38affects other things such as whether the path has the drive part or not.
39
40\begin{verbatim}
41enum wxPathFormat
42{
43 wxPATH_NATIVE = 0, // the path format for the current platform
44 wxPATH_UNIX,
45 wxPATH_BEOS = wxPATH_UNIX,
46 wxPATH_MAC,
47 wxPATH_DOS,
48 wxPATH_WIN = wxPATH_DOS,
49 wxPATH_OS2 = wxPATH_DOS,
50 wxPATH_VMS,
51
52 wxPATH_MAX // Not a valid value for specifying path format
53}
54\end{verbatim}
55
56\latexignore{\rtfignore{\wxheading{Function groups}}}
57
58
59\membersection{File name format}\label{filenameformat}
60
61wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
62and VMS formats. Although these formats are quite different, wxFileName tries
63to treat them all in the same generic way. It supposes that all file names
64consist of the following parts: the volume (also known as drive under Windows
65or device under VMS), the path which is a sequence of directory names separated
66by the \helpref{path separators}{wxfilenamegetpathseparators} and the full
67filename itself which, in turn, is composed from the base file name and the
68extension. All of the individual components of the file name may be empty and,
69for example, the volume name is always empty under Unix, but if they are all
70empty simultaneously, the filename object is considered to be in an invalid
71state and \helpref{IsOk}{wxfilenameisok} returns {\tt false} for it.
72
73File names can be case-sensitive or not, the function\rtfsp
74\helpref{IsCaseSensitive}{wxfilenameiscasesensitive} allows to determine this.
75
76The rules for determining if the file name is absolute or relative also depends
77on the file name format and the only portable way to answer to this question is
78to use \helpref{IsAbsolute}{wxfilenameisabsolute} method. To ensure that the
79filename is absolute you may use \helpref{MakeAbsolute}{wxfilenamemakeabsolute}.
80There is also an inverse function
81\helpref{MakeRelativeTo}{wxfilenamemakerelativeto} which undoes what
82\helpref{Normalize(wxPATH\_NORM\_DOTS)}{wxfilenamenormalize} does.
83
84Other functions returning information about the file format provided by this
85class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp
86\helpref{IsPathSeparator}{wxfilenameispathseparator}.
87
88\helpref{IsRelative}{wxfilenameisrelative}
89
90
91\membersection{File name construction}\label{filenameconstruction}
92
93TODO.
94
95
96\membersection{File tests}\label{filetests}
97
98Before doing the other tests you should use \helpref{IsOk}{wxfilenameisok} to
99verify that the filename is well defined. If it is,
100\helpref{FileExists}{wxfilenamefileexists} can be used to test if a file with
101such name exists and \helpref{DirExists}{wxfilenamedirexists} - if a directory
102with this name exists.
103
104File names should be compared using \helpref{SameAs}{wxfilenamesameas} method
105or \helpref{$==$}{wxfilenameoperatorequal}.
106
107
108\membersection{File name components}\label{filenamecomponents}
109
110These functions allow to examine and modify the individual directories of the
111path:
112
113\helpref{AppendDir}{wxfilenameappenddir}\\
114\helpref{InsertDir}{wxfilenameinsertdir}\\
115\helpref{GetDirCount}{wxfilenamegetdircount}
116\helpref{PrependDir}{wxfilenameprependdir}\\
117\helpref{RemoveDir}{wxfilenameremovedir}\\
118\helpref{RemoveLastDir}{wxfilenameremovelastdir}
119
120To change the components of the file name individually you can use the
121following functions:
122
123\helpref{GetExt}{wxfilenamegetext}\\
124\helpref{GetName}{wxfilenamegetname}\\
125\helpref{GetVolume}{wxfilenamegetvolume}\\
126\helpref{HasExt}{wxfilenamehasext}\\
127\helpref{HasName}{wxfilenamehasname}\\
128\helpref{HasVolume}{wxfilenamehasvolume}\\
129\helpref{SetExt}{wxfilenamesetext}\\
130\helpref{SetName}{wxfilenamesetname}\\
131\helpref{SetVolume}{wxfilenamesetvolume}\\
132
133
134\membersection{Operations}\label{filenameoperations}
135
136These methods allow to work with the file creation, access and modification
137times. Note that not all filesystems under all platforms implement these times
138in the same way. For example, the access time under Windows has a resolution of
139one day (so it is really the access date and not time). The access time may be
140updated when the file is executed or not depending on the platform.
141
142\helpref{GetModificationTime}{wxfilenamegetmodificationtime}\\
143\helpref{GetTimes}{wxfilenamegettimes}\\
144\helpref{SetTimes}{wxfilenamesettimes}\\
145\helpref{Touch}{wxfilenametouch}
146
147Other file system operations functions are:
148
149\helpref{Mkdir}{wxfilenamemkdir}\\
150\helpref{Rmdir}{wxfilenamermdir}
151
152\latexignore{\rtfignore{\wxheading{Members}}}
153
154
155\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename}
156
157\func{}{wxFileName}{\void}
158
159Default constructor.
160
161\func{}{wxFileName}{\param{const wxFileName\& }{filename}}
162
163Copy constructor.
164
165\func{}{wxFileName}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
166
167Constructor taking a full filename. If it terminates with a '/', a directory path
168is constructed (the name will be empty), otherwise a file name and
169extension are extracted from it.
170
171\func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
172
173Constructor from a directory name and a file name.
174
175\func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
176
177Constructor from a directory name, base file name and extension.
178
179\func{}{wxFileName}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
180
181Constructor from a volume name, a directory name, base file name and extension.
182
183
184\membersection{wxFileName::AppendDir}\label{wxfilenameappenddir}
185
186\func{void}{AppendDir}{\param{const wxString\& }{dir}}
187
188Appends a directory component to the path. This component should contain a
189single directory name level, i.e. not contain any path or volume separators nor
190should it be empty, otherwise the function does nothing (and generates an
191assert failure in debug build).
192
193
194\membersection{wxFileName::Assign}\label{wxfilenameassign}
195
196\func{void}{Assign}{\param{const wxFileName\& }{filepath}}
197
198\func{void}{Assign}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
199
200\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}}
201
202\func{void}{Assign}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
203
204\func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
205
206\func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
207
208Creates the file name from various combinations of data.
209
210
211\membersection{wxFileName::AssignCwd}\label{wxfilenameassigncwd}
212
213\func{static void}{AssignCwd}{\param{const wxString\& }{volume = wxEmptyString}}
214
215Makes this object refer to the current working directory on the specified
216volume (or current volume if {\it volume} is empty).
217
218\wxheading{See also}
219
220\helpref{GetCwd}{wxfilenamegetcwd}
221
222
223\membersection{wxFileName::AssignDir}\label{wxfilenameassigndir}
224
225\func{void}{AssignDir}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
226
227Sets this file name object to the given directory name. The name and extension
228will be empty.
229
230
231\membersection{wxFileName::AssignHomeDir}\label{wxfilenameassignhomedir}
232
233\func{void}{AssignHomeDir}{\void}
234
235Sets this file name object to the home directory.
236
237
238\membersection{wxFileName::AssignTempFileName}\label{wxfilenameassigntempfilename}
239
240\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}}
241
242The function calls \helpref{CreateTempFileName}{wxfilenamecreatetempfilename} to
243create a temporary file and sets this object to the name of the file. If a
244temporary file couldn't be created, the object is put into the\rtfsp
245\helpref{invalid}{wxfilenameisok} state.
246
247
248\membersection{wxFileName::Clear}\label{wxfilenameclear}
249
250\func{void}{Clear}{\void}
251
252Reset all components to default, uninitialized state.
253
254
255\membersection{wxFileName::CreateTempFileName}\label{wxfilenamecreatetempfilename}
256
257\func{static wxString}{CreateTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}}
258
259Returns a temporary file name starting with the given {\it prefix}. If
260the {\it prefix} is an absolute path, the temporary file is created in this
261directory, otherwise it is created in the default system directory for the
262temporary files or in the current directory.
263
264If the function succeeds, the temporary file is actually created. If\rtfsp
265{\it fileTemp} is not {\tt NULL}, this file will be opened using the name of
266the temporary file. When possible, this is done in an atomic way ensuring that
267no race condition occurs between the temporary file name generation and opening
268it which could often lead to security compromise on the multiuser systems.
269If {\it fileTemp} is {\tt NULL}, the file is only created, but not opened.
270
271Under Unix, the temporary file will have read and write permissions for the
272owner only to minimize the security problems.
273
274\wxheading{Parameters}
275
276\docparam{prefix}{Prefix to use for the temporary file name construction}
277
278\docparam{fileTemp}{The file to open or {\tt NULL} to just get the name}
279
280\wxheading{Return value}
281
282The full temporary file name or an empty string on error.
283
284
285\membersection{wxFileName::DirExists}\label{wxfilenamedirexists}
286
287\constfunc{bool}{DirExists}{\void}
288
289\func{static bool}{DirExists}{\param{const wxString\& }{dir}}
290
291Returns {\tt true} if the directory with this name exists.
292
293
294\membersection{wxFileName::DirName}\label{wxfilenamedirname}
295
296\func{static wxFileName}{DirName}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
297
298Returns the object corresponding to the directory with the given name.
299The {\it dir} parameter may have trailing path separator or not.
300
301
302
303\membersection{wxFileName::FileExists}\label{wxfilenamefileexists}
304
305\constfunc{bool}{FileExists}{\void}
306
307\func{static bool}{FileExists}{\param{const wxString\& }{file}}
308
309Returns {\tt true} if the file with this name exists.
310
311\wxheading{See also}
312
313\helpref{DirExists}{wxfilenamedirexists}
314
315
316
317\membersection{wxFileName::FileName}\label{wxfilenamefilename}
318
319\func{static wxFileName}{FileName}{\param{const wxString\& }{file}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
320
321Returns the file name object corresponding to the given {\it file}. This
322function exists mainly for symmetry with \helpref{DirName}{wxfilenamedirname}.
323
324
325
326\membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd}
327
328\func{static wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}
329
330Retrieves the value of the current working directory on the specified volume. If
331the volume is empty, the programs current working directory is returned for the
332current volume.
333
334\wxheading{Return value}
335
336The string containing the current working directory or an empty string on
337error.
338
339\wxheading{See also}
340
341\helpref{AssignCwd}{wxfilenameassigncwd}
342
343
344\membersection{wxFileName::GetDirCount}\label{wxfilenamegetdircount}
345
346\constfunc{size\_t}{GetDirCount}{\void}
347
348Returns the number of directories in the file name.
349
350
351\membersection{wxFileName::GetDirs}\label{wxfilenamegetdirs}
352
353\constfunc{const wxArrayString\&}{GetDirs}{\void}
354
355Returns the directories in string array form.
356
357
358\membersection{wxFileName::GetExt}\label{wxfilenamegetext}
359
360\constfunc{wxString}{GetExt}{\void}
361
362Returns the file name extension.
363
364
365\membersection{wxFileName::GetForbiddenChars}\label{wxfilenamegetforbiddenchars}
366
367\func{static wxString}{GetForbiddenChars}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
368
369Returns the characters that can't be used in filenames and directory names for the specified format.
370
371
372\membersection{wxFileName::GetFormat}\label{wxfilenamegetformat}
373
374\func{static wxPathFormat}{GetFormat}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
375
376Returns the canonical path format for this platform.
377
378
379\membersection{wxFileName::GetFullName}\label{wxfilenamegetfullname}
380
381\constfunc{wxString}{GetFullName}{\void}
382
383Returns the full name (including extension but excluding directories).
384
385
386\membersection{wxFileName::GetFullPath}\label{wxfilenamegetfullpath}
387
388\constfunc{wxString}{GetFullPath}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
389
390Returns the full path with name and extension.
391
392
393\membersection{wxFileName::GetHomeDir}\label{wxfilenamegethomedir}
394
395\func{static wxString}{GetHomeDir}{\void}
396
397Returns the home directory.
398
399
400\membersection{wxFileName::GetLongPath}\label{wxfilenamegetlongpath}
401
402\constfunc{wxString}{GetLongPath}{\void}
403
404Return the long form of the path (returns identity on non-Windows platforms)
405
406
407\membersection{wxFileName::GetModificationTime}\label{wxfilenamegetmodificationtime}
408
409\constfunc{wxDateTime}{GetModificationTime}{\void}
410
411Returns the last time the file was last modified.
412
413
414\membersection{wxFileName::GetName}\label{wxfilenamegetname}
415
416\constfunc{wxString}{GetName}{\void}
417
418Returns the name part of the filename.
419
420
421\membersection{wxFileName::GetPath}\label{wxfilenamegetpath}
422
423\constfunc{wxString}{GetPath}{\param{int }{flags = {\tt wxPATH\_GET\_VOLUME}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
424
425Returns the path part of the filename (without the name or extension). The
426possible flags values are:
427
428\twocolwidtha{5cm}
429\begin{twocollist}\itemsep=0pt
430\twocolitem{{\bf wxPATH\_GET\_VOLUME}}{Return the path with the volume (does
431nothing for the filename formats without volumes), otherwise the path without
432volume part is returned.}
433\twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing
434separator, if this flag is not given there will be no separator at the end of
435the path.}
436\end{twocollist}
437
438
439\membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator}
440
441\func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
442
443Returns the usually used path separator for this format. For all formats but
444{\tt wxPATH\_DOS} there is only one path separator anyhow, but for DOS there
445are two of them and the native one, i.e. the backslash is returned by this
446method.
447
448\wxheading{See also}
449
450\helpref{GetPathSeparators}{wxfilenamegetpathseparators}
451
452
453\membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators}
454
455\func{static wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
456
457Returns the string containing all the path separators for this format. For all
458formats but {\tt wxPATH\_DOS} this string contains only one character but for
459DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as
460separators.
461
462\wxheading{See also}
463
464\helpref{GetPathSeparator}{wxfilenamegetpathseparator}
465
466
467\membersection{wxFileName::GetPathTerminators}\label{wxfilenamegetpathterminators}
468
469\func{static wxString}{GetPathTerminators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
470
471Returns the string of characters which may terminate the path part. This is the
472same as \helpref{GetPathSeparators}{wxfilenamegetpathseparators} except for VMS
473path format where $]$ is used at the end of the path part.
474
475
476\membersection{wxFileName::GetShortPath}\label{wxfilenamegetshortpath}
477
478\constfunc{wxString}{GetShortPath}{\void}
479
480Return the short form of the path (returns identity on non-Windows platforms).
481
482
483\membersection{wxFileName::GetTimes}\label{wxfilenamegettimes}
484
485\constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}
486
487Returns the last access, last modification and creation times. The last access
488time is updated whenever the file is read or written (or executed in the case
489of Windows), last modification time is only changed when the file is written
490to. Finally, the creation time is indeed the time when the file was created
491under Windows and the inode change time under Unix (as it is impossible to
492retrieve the real file creation time there anyhow) which can also be changed
493by many operations after the file creation.
494
495Any of the pointers may be {\tt NULL} if the corresponding time is not
496needed.
497
498\wxheading{Return value}
499
500{\tt true} on success, {\tt false} if we failed to retrieve the times.
501
502
503\membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume}
504
505\constfunc{wxString}{GetVolume}{\void}
506
507Returns the string containing the volume for this file name, empty if it
508doesn't have one or if the file system doesn't support volumes at all (for
509example, Unix).
510
511
512\membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
513
514\func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
515
516Returns the string separating the volume from the path for this format.
517
518
519\membersection{wxFileName::HasExt}\label{wxfilenamehasext}
520
521\constfunc{bool}{HasExt}{\void}
522
523Returns {\tt true} if an extension is present.
524
525
526\membersection{wxFileName::HasName}\label{wxfilenamehasname}
527
528\constfunc{bool}{HasName}{\void}
529
530Returns {\tt true} if a name is present.
531
532
533\membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
534
535\constfunc{bool}{HasVolume}{\void}
536
537Returns {\tt true} if a volume specifier is present.
538
539
540\membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir}
541
542\func{void}{InsertDir}{\param{size\_t }{before}, \param{const wxString\& }{dir}}
543
544Inserts a directory component before the zero-based position in the directory
545list. Please see \helpref{AppendDir}{wxfilenameappenddir} for important notes.
546
547
548\membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute}
549
550\func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
551
552Returns {\tt true} if this filename is absolute.
553
554
555\membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive}
556
557\func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
558
559Returns {\tt true} if the file names of this type are case-sensitive.
560
561
562\membersection{wxFileName::IsOk}\label{wxfilenameisok}
563
564\constfunc{bool}{IsOk}{\void}
565
566Returns {\tt true} if the filename is valid, {\tt false} if it is not
567initialized yet. The assignment functions and
568\helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized,
569invalid state (the former only do it on failure).
570
571
572\membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator}
573
574\func{static bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
575
576Returns {\tt true} if the char is a path separator for this format.
577
578
579\membersection{wxFileName::IsRelative}\label{wxfilenameisrelative}
580
581\func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
582
583Returns {\tt true} if this filename is not absolute.
584
585
586\membersection{wxFileName::IsDir}\label{wxfilenameisdir}
587
588\constfunc{bool}{IsDir}{\void}
589
590Returns {\tt true} if this object represents a directory, {\tt false} otherwise
591(i.e. if it is a file). Note that this method doesn't test whether the
592directory or file really exists, you should use
593\helpref{DirExists}{wxfilenamedirexists} or
594\helpref{FileExists}{wxfilenamefileexists} for this.
595
596\membersection{wxFileName::MacFindDefaultTypeAndCreator}\label{wxfilenamemacfinddefaulttypeandcreator}
597
598\func{static bool}{MacFindDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32* }{type}, \param{wxUint32* }{creator}}
599
600On Mac OS, gets the common type and creator for the given extension.
601
602\membersection{wxFileName::MacRegisterDefaultTypeAndCreator}\label{wxfilenamemacregisterdefaulttypeandcreator}
603
604\func{static void}{MacRegisterDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32 }{type}, \param{wxUint32 }{creator}}
605
606On Mac OS, registers application defined extensions and their default type and creator.
607
608\membersection{wxFileName::MacSetDefaultTypeAndCreator}\label{wxfilenamemacsetdefaulttypeandcreator}
609
610\func{bool}{MacSetDefaultTypeAndCreator}{\void}
611
612On Mac OS, looks up the appropriate type and creator from the registration and then sets it.
613
614\membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute}
615
616\func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
617
618Make the file name absolute. This is a shortcut for
619{\tt \helpref{Normalize}{wxfilenamenormalize}(wxPATH\_NORM\_DOTS | wxPATH\_NORM\_ABSOLUTE | wxPATH\_NORM\_TILDE, cwd, format)}.
620
621\wxheading{See also}
622
623\helpref{MakeRelativeTo}{wxfilenamemakerelativeto},
624\helpref{Normalize}{wxfilenamenormalize},
625\helpref{IsAbsolute}{wxfilenameisabsolute}
626
627
628\membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto}
629
630\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
631
632This function tries to put this file name in a form relative to {\it pathBase}.
633In other words, it returns the file name which should be used to access this
634file if the current directory were {\it pathBase}.
635
636\docparam{pathBase}{the directory to use as root, current directory is used by
637default}
638
639\docparam{format}{the file name format, native by default}
640
641\wxheading{Return value}
642
643{\tt true} if the file name has been changed, {\tt false} if we failed to do
644anything with it (currently this only happens if the file name is on a volume
645different from the volume specified by {\it pathBase}).
646
647\wxheading{See also}
648
649\helpref{Normalize}{wxfilenamenormalize}
650
651
652\membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
653
654\func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}}
655
656\func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}}
657
658\docparam{dir}{the directory to create}
659
660\docparam{parm}{the permissions for the newly created directory}
661
662\docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag,
663try to create each directory in the path and also don't return an error
664if the target directory already exists.}
665
666\wxheading{Return value}
667
668Returns {\tt true} if the directory was successfully created, {\tt false}
669otherwise.
670
671
672\membersection{wxFileName::Normalize}\label{wxfilenamenormalize}
673
674\func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
675
676Normalize the path. With the default flags value, the path will be
677made absolute, without any ".." and "." and all environment
678variables will be expanded in it.
679
680\docparam{flags}{The kind of normalization to do with the file name. It can be
681any or-combination of the following constants:
682
683\begin{twocollist}
684\twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values}
685\twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . and prepend cwd}
686\twocolitem{{\bf wxPATH\_NORM\_TILDE}}{Unix only: replace ~ and ~user}
687\twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to tolower case}
688\twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute}
689\twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form}
690\twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)}
691\twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}}
692\end{twocollist}
693}%
694
695\docparam{cwd}{If not empty, this directory will be used instead of current
696working directory in normalization.}
697
698\docparam{format}{The file name format, native by default.}
699
700
701\membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}
702
703\func{void}{PrependDir}{\param{const wxString\& }{dir}}
704
705Prepends a directory to the file path. Please see
706\helpref{AppendDir}{wxfilenameappenddir} for important notes.
707
708
709
710\membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir}
711
712\func{void}{RemoveDir}{\param{size\_t }{pos}}
713
714Removes the specified directory component from the path.
715
716\wxheading{See also}
717
718\helpref{GetDirCount}{wxfilenamegetdircount}
719
720
721\membersection{wxFileName::RemoveLastDir}\label{wxfilenameremovelastdir}
722
723\func{void}{RemoveLastDir}{\void}
724
725Removes last directory component from the path.
726
727
728\membersection{wxFileName::Rmdir}\label{wxfilenamermdir}
729
730\func{bool}{Rmdir}{\void}
731
732\func{static bool}{Rmdir}{\param{const wxString\& }{dir}}
733
734Deletes the specified directory from the file system.
735
736
737\membersection{wxFileName::SameAs}\label{wxfilenamesameas}
738
739\constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
740
741Compares the filename using the rules of this platform.
742
743
744\membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
745
746\func{bool}{SetCwd}{\void}
747
748\func{static bool}{SetCwd}{\param{const wxString\& }{cwd}}
749
750Changes the current working directory.
751
752
753\membersection{wxFileName::SetExt}\label{wxfilenamesetext}
754
755\func{void}{SetExt}{\param{const wxString\& }{ext}}
756
757Sets the extension of this file name.
758
759
760\membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname}
761
762\func{void}{SetFullName}{\param{const wxString\& }{fullname}}
763
764The full name is the file name and extension (but without the path).
765
766
767\membersection{wxFileName::SetName}\label{wxfilenamesetname}
768
769\func{void}{SetName}{\param{const wxString\& }{name}}
770
771Sets the name.
772
773
774\membersection{wxFileName::SetTimes}\label{wxfilenamesettimes}
775
776\func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}}
777
778Sets the file creation and last access/modification times (any of the pointers may be NULL).
779
780
781\membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume}
782
783\func{void}{SetVolume}{\param{const wxString\& }{volume}}
784
785Sets the volume specifier.
786
787
788\membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath}
789
790\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}}
791
792\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}}
793
794\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
795
796This function splits a full file name into components: the volume (with the
797first version) path (including the volume in the second version), the base name
798and the extension. Any of the output parameters ({\it volume}, {\it path},
799{\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the
800value of a particular component. Also, {\it fullpath} may be empty on entry.
801
802On return, {\it path} contains the file path (without the trailing separator),
803{\it name} contains the file name and {\it ext} contains the file extension
804without leading dot. All three of them may be empty if the corresponding
805component is. The old contents of the strings pointed to by these parameters
806will be overwritten in any case (if the pointers are not {\tt NULL}).
807
808Note that for a filename ``foo.'' the extension is present, as indicated by the
809trailing dot, but empty. If you need to cope with such cases, you should use
810\arg{hasExt} instead of relying on testing whether \arg{ext} is empty or not.
811
812
813\membersection{wxFileName::SplitVolume}\label{wxfilenamesplitvolume}
814
815\func{static void}{SplitVolume}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
816
817Splits the given \arg{fullpath} into the volume part (which may be empty) and
818the pure path part, not containing any volume.
819
820\wxheading{See also}
821
822\helpref{SplitPath}{wxfilenamesplitpath}
823
824
825\membersection{wxFileName::Touch}\label{wxfilenametouch}
826
827\func{bool}{Touch}{\void}
828
829Sets the access and modification times to the current moment.
830
831
832\membersection{wxFileName::operator=}\label{wxfilenameoperatorassign}
833
834\func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}}
835
836\func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}}
837
838Assigns the new value to this filename object.
839
840
841\membersection{wxFileName::operator==}\label{wxfilenameoperatorequal}
842
843\constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}}
844
845\constfunc{bool operator}{operator==}{\param{const wxString\& }{filename}}
846
847Returns {\tt true} if the filenames are equal. The string {\it filenames} is
848interpreted as a path in the native filename format.
849
850
851\membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal}
852
853\constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}}
854
855\constfunc{bool operator}{operator!=}{\param{const wxString\& }{filename}}
856
857Returns {\tt true} if the filenames are different. The string {\it filenames}
858is interpreted as a path in the native filename format.
859