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