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