]>
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: 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 (without extension). | |
433 | ||
434 | \wxheading{See also} | |
435 | ||
436 | \helpref{GetFullName}{wxfilenamegetfullname} | |
437 | ||
438 | ||
439 | ||
440 | \membersection{wxFileName::GetPath}\label{wxfilenamegetpath} | |
441 | ||
442 | \constfunc{wxString}{GetPath}{\param{int }{flags = {\tt wxPATH\_GET\_VOLUME}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
443 | ||
444 | Returns the path part of the filename (without the name or extension). The | |
445 | possible flags values are: | |
446 | ||
447 | \twocolwidtha{5cm} | |
448 | \begin{twocollist}\itemsep=0pt | |
449 | \twocolitem{{\bf wxPATH\_GET\_VOLUME}}{Return the path with the volume (does | |
450 | nothing for the filename formats without volumes), otherwise the path without | |
451 | volume part is returned.} | |
452 | \twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing | |
453 | separator, if this flag is not given there will be no separator at the end of | |
454 | the path.} | |
455 | \end{twocollist} | |
456 | ||
457 | ||
458 | \membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator} | |
459 | ||
460 | \func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
461 | ||
462 | Returns the usually used path separator for this format. For all formats but | |
463 | {\tt wxPATH\_DOS} there is only one path separator anyhow, but for DOS there | |
464 | are two of them and the native one, i.e. the backslash is returned by this | |
465 | method. | |
466 | ||
467 | \wxheading{See also} | |
468 | ||
469 | \helpref{GetPathSeparators}{wxfilenamegetpathseparators} | |
470 | ||
471 | ||
472 | \membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators} | |
473 | ||
474 | \func{static wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
475 | ||
476 | Returns the string containing all the path separators for this format. For all | |
477 | formats but {\tt wxPATH\_DOS} this string contains only one character but for | |
478 | DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as | |
479 | separators. | |
480 | ||
481 | \wxheading{See also} | |
482 | ||
483 | \helpref{GetPathSeparator}{wxfilenamegetpathseparator} | |
484 | ||
485 | ||
486 | \membersection{wxFileName::GetPathTerminators}\label{wxfilenamegetpathterminators} | |
487 | ||
488 | \func{static wxString}{GetPathTerminators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
489 | ||
490 | Returns the string of characters which may terminate the path part. This is the | |
491 | same as \helpref{GetPathSeparators}{wxfilenamegetpathseparators} except for VMS | |
492 | path format where $]$ is used at the end of the path part. | |
493 | ||
494 | ||
495 | \membersection{wxFileName::GetShortPath}\label{wxfilenamegetshortpath} | |
496 | ||
497 | \constfunc{wxString}{GetShortPath}{\void} | |
498 | ||
499 | Return the short form of the path (returns identity on non-Windows platforms). | |
500 | ||
501 | ||
502 | \membersection{wxFileName::GetTimes}\label{wxfilenamegettimes} | |
503 | ||
504 | \constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}} | |
505 | ||
506 | Returns the last access, last modification and creation times. The last access | |
507 | time is updated whenever the file is read or written (or executed in the case | |
508 | of Windows), last modification time is only changed when the file is written | |
509 | to. Finally, the creation time is indeed the time when the file was created | |
510 | under Windows and the inode change time under Unix (as it is impossible to | |
511 | retrieve the real file creation time there anyhow) which can also be changed | |
512 | by many operations after the file creation. | |
513 | ||
514 | Any of the pointers may be {\tt NULL} if the corresponding time is not | |
515 | needed. | |
516 | ||
517 | \wxheading{Return value} | |
518 | ||
519 | {\tt true} on success, {\tt false} if we failed to retrieve the times. | |
520 | ||
521 | ||
522 | \membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume} | |
523 | ||
524 | \constfunc{wxString}{GetVolume}{\void} | |
525 | ||
526 | Returns the string containing the volume for this file name, empty if it | |
527 | doesn't have one or if the file system doesn't support volumes at all (for | |
528 | example, Unix). | |
529 | ||
530 | ||
531 | \membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator} | |
532 | ||
533 | \func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
534 | ||
535 | Returns the string separating the volume from the path for this format. | |
536 | ||
537 | ||
538 | \membersection{wxFileName::HasExt}\label{wxfilenamehasext} | |
539 | ||
540 | \constfunc{bool}{HasExt}{\void} | |
541 | ||
542 | Returns {\tt true} if an extension is present. | |
543 | ||
544 | ||
545 | \membersection{wxFileName::HasName}\label{wxfilenamehasname} | |
546 | ||
547 | \constfunc{bool}{HasName}{\void} | |
548 | ||
549 | Returns {\tt true} if a name is present. | |
550 | ||
551 | ||
552 | \membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume} | |
553 | ||
554 | \constfunc{bool}{HasVolume}{\void} | |
555 | ||
556 | Returns {\tt true} if a volume specifier is present. | |
557 | ||
558 | ||
559 | \membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir} | |
560 | ||
561 | \func{void}{InsertDir}{\param{size\_t }{before}, \param{const wxString\& }{dir}} | |
562 | ||
563 | Inserts a directory component before the zero-based position in the directory | |
564 | list. Please see \helpref{AppendDir}{wxfilenameappenddir} for important notes. | |
565 | ||
566 | ||
567 | \membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute} | |
568 | ||
569 | \func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
570 | ||
571 | Returns {\tt true} if this filename is absolute. | |
572 | ||
573 | ||
574 | \membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive} | |
575 | ||
576 | \func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
577 | ||
578 | Returns {\tt true} if the file names of this type are case-sensitive. | |
579 | ||
580 | ||
581 | \membersection{wxFileName::IsOk}\label{wxfilenameisok} | |
582 | ||
583 | \constfunc{bool}{IsOk}{\void} | |
584 | ||
585 | Returns {\tt true} if the filename is valid, {\tt false} if it is not | |
586 | initialized yet. The assignment functions and | |
587 | \helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized, | |
588 | invalid state (the former only do it on failure). | |
589 | ||
590 | ||
591 | \membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator} | |
592 | ||
593 | \func{static bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
594 | ||
595 | Returns {\tt true} if the char is a path separator for this format. | |
596 | ||
597 | ||
598 | \membersection{wxFileName::IsRelative}\label{wxfilenameisrelative} | |
599 | ||
600 | \func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
601 | ||
602 | Returns {\tt true} if this filename is not absolute. | |
603 | ||
604 | ||
605 | \membersection{wxFileName::IsDir}\label{wxfilenameisdir} | |
606 | ||
607 | \constfunc{bool}{IsDir}{\void} | |
608 | ||
609 | Returns {\tt true} if this object represents a directory, {\tt false} otherwise | |
610 | (i.e. if it is a file). Note that this method doesn't test whether the | |
611 | directory or file really exists, you should use | |
612 | \helpref{DirExists}{wxfilenamedirexists} or | |
613 | \helpref{FileExists}{wxfilenamefileexists} for this. | |
614 | ||
615 | \membersection{wxFileName::MacFindDefaultTypeAndCreator}\label{wxfilenamemacfinddefaulttypeandcreator} | |
616 | ||
617 | \func{static bool}{MacFindDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32* }{type}, \param{wxUint32* }{creator}} | |
618 | ||
619 | On Mac OS, gets the common type and creator for the given extension. | |
620 | ||
621 | \membersection{wxFileName::MacRegisterDefaultTypeAndCreator}\label{wxfilenamemacregisterdefaulttypeandcreator} | |
622 | ||
623 | \func{static void}{MacRegisterDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32 }{type}, \param{wxUint32 }{creator}} | |
624 | ||
625 | On Mac OS, registers application defined extensions and their default type and creator. | |
626 | ||
627 | \membersection{wxFileName::MacSetDefaultTypeAndCreator}\label{wxfilenamemacsetdefaulttypeandcreator} | |
628 | ||
629 | \func{bool}{MacSetDefaultTypeAndCreator}{\void} | |
630 | ||
631 | On Mac OS, looks up the appropriate type and creator from the registration and then sets it. | |
632 | ||
633 | \membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute} | |
634 | ||
635 | \func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
636 | ||
637 | Make the file name absolute. This is a shortcut for | |
638 | {\tt \helpref{Normalize}{wxfilenamenormalize}(wxPATH\_NORM\_DOTS | wxPATH\_NORM\_ABSOLUTE | wxPATH\_NORM\_TILDE, cwd, format)}. | |
639 | ||
640 | \wxheading{See also} | |
641 | ||
642 | \helpref{MakeRelativeTo}{wxfilenamemakerelativeto}, | |
643 | \helpref{Normalize}{wxfilenamenormalize}, | |
644 | \helpref{IsAbsolute}{wxfilenameisabsolute} | |
645 | ||
646 | ||
647 | \membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto} | |
648 | ||
649 | \func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
650 | ||
651 | This function tries to put this file name in a form relative to {\it pathBase}. | |
652 | In other words, it returns the file name which should be used to access this | |
653 | file if the current directory were {\it pathBase}. | |
654 | ||
655 | \docparam{pathBase}{the directory to use as root, current directory is used by | |
656 | default} | |
657 | ||
658 | \docparam{format}{the file name format, native by default} | |
659 | ||
660 | \wxheading{Return value} | |
661 | ||
662 | {\tt true} if the file name has been changed, {\tt false} if we failed to do | |
663 | anything with it (currently this only happens if the file name is on a volume | |
664 | different from the volume specified by {\it pathBase}). | |
665 | ||
666 | \wxheading{See also} | |
667 | ||
668 | \helpref{Normalize}{wxfilenamenormalize} | |
669 | ||
670 | ||
671 | \membersection{wxFileName::Mkdir}\label{wxfilenamemkdir} | |
672 | ||
673 | \func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}} | |
674 | ||
675 | \func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}} | |
676 | ||
677 | \docparam{dir}{the directory to create} | |
678 | ||
679 | \docparam{parm}{the permissions for the newly created directory} | |
680 | ||
681 | \docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag, | |
682 | try to create each directory in the path and also don't return an error | |
683 | if the target directory already exists.} | |
684 | ||
685 | \wxheading{Return value} | |
686 | ||
687 | Returns {\tt true} if the directory was successfully created, {\tt false} | |
688 | otherwise. | |
689 | ||
690 | ||
691 | \membersection{wxFileName::Normalize}\label{wxfilenamenormalize} | |
692 | ||
693 | \func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
694 | ||
695 | Normalize the path. With the default flags value, the path will be | |
696 | made absolute, without any ".." and "." and all environment | |
697 | variables will be expanded in it. | |
698 | ||
699 | \docparam{flags}{The kind of normalization to do with the file name. It can be | |
700 | any or-combination of the following constants: | |
701 | ||
702 | \begin{twocollist} | |
703 | \twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values} | |
704 | \twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . and prepend cwd} | |
705 | \twocolitem{{\bf wxPATH\_NORM\_TILDE}}{Unix only: replace ~ and ~user} | |
706 | \twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to lower case} | |
707 | \twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute} | |
708 | \twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form} | |
709 | \twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)} | |
710 | \twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}} | |
711 | \end{twocollist} | |
712 | }% | |
713 | ||
714 | \docparam{cwd}{If not empty, this directory will be used instead of current | |
715 | working directory in normalization.} | |
716 | ||
717 | \docparam{format}{The file name format, native by default.} | |
718 | ||
719 | ||
720 | \membersection{wxFileName::PrependDir}\label{wxfilenameprependdir} | |
721 | ||
722 | \func{void}{PrependDir}{\param{const wxString\& }{dir}} | |
723 | ||
724 | Prepends a directory to the file path. Please see | |
725 | \helpref{AppendDir}{wxfilenameappenddir} for important notes. | |
726 | ||
727 | ||
728 | ||
729 | \membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir} | |
730 | ||
731 | \func{void}{RemoveDir}{\param{size\_t }{pos}} | |
732 | ||
733 | Removes the specified directory component from the path. | |
734 | ||
735 | \wxheading{See also} | |
736 | ||
737 | \helpref{GetDirCount}{wxfilenamegetdircount} | |
738 | ||
739 | ||
740 | \membersection{wxFileName::RemoveLastDir}\label{wxfilenameremovelastdir} | |
741 | ||
742 | \func{void}{RemoveLastDir}{\void} | |
743 | ||
744 | Removes last directory component from the path. | |
745 | ||
746 | ||
747 | \membersection{wxFileName::Rmdir}\label{wxfilenamermdir} | |
748 | ||
749 | \func{bool}{Rmdir}{\void} | |
750 | ||
751 | \func{static bool}{Rmdir}{\param{const wxString\& }{dir}} | |
752 | ||
753 | Deletes the specified directory from the file system. | |
754 | ||
755 | ||
756 | \membersection{wxFileName::SameAs}\label{wxfilenamesameas} | |
757 | ||
758 | \constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
759 | ||
760 | Compares the filename using the rules of this platform. | |
761 | ||
762 | ||
763 | \membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd} | |
764 | ||
765 | \func{bool}{SetCwd}{\void} | |
766 | ||
767 | \func{static bool}{SetCwd}{\param{const wxString\& }{cwd}} | |
768 | ||
769 | Changes the current working directory. | |
770 | ||
771 | ||
772 | \membersection{wxFileName::SetExt}\label{wxfilenamesetext} | |
773 | ||
774 | \func{void}{SetExt}{\param{const wxString\& }{ext}} | |
775 | ||
776 | Sets the extension of the file name. Setting an empty string | |
777 | as the extension will remove the extension resulting in a file | |
778 | name without a trailing dot, unlike a call to | |
779 | \helpref{SetEmptyExt}{wxfilenamesetemptyext}. | |
780 | ||
781 | \wxheading{See also} | |
782 | ||
783 | \helpref{SetEmptyExt}{wxfilenamesetemptyext} | |
784 | \helpref{ClearExt}{wxfilenameclearext} | |
785 | ||
786 | \membersection{wxFileName::SetEmptyExt}\label{wxfilenamesetemptyext} | |
787 | ||
788 | \func{void}{SetEmptyExt}{\void} | |
789 | ||
790 | Sets the extension of the file name to be an empty extension. | |
791 | This is different from having no extension at all as the file | |
792 | name will have a trailing dot after a call to this method. | |
793 | ||
794 | \wxheading{See also} | |
795 | ||
796 | \helpref{SetExt}{wxfilenamesetext} | |
797 | \helpref{ClearExt}{wxfilenameclearext} | |
798 | ||
799 | \membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname} | |
800 | ||
801 | \func{void}{SetFullName}{\param{const wxString\& }{fullname}} | |
802 | ||
803 | The full name is the file name and extension (but without the path). | |
804 | ||
805 | ||
806 | \membersection{wxFileName::SetName}\label{wxfilenamesetname} | |
807 | ||
808 | \func{void}{SetName}{\param{const wxString\& }{name}} | |
809 | ||
810 | Sets the name part (without extension). | |
811 | ||
812 | \wxheading{See also} | |
813 | ||
814 | \helpref{SetFullName}{wxfilenamesetfullname} | |
815 | ||
816 | ||
817 | \membersection{wxFileName::SetTimes}\label{wxfilenamesettimes} | |
818 | ||
819 | \func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}} | |
820 | ||
821 | Sets the file creation and last access/modification times (any of the pointers may be NULL). | |
822 | ||
823 | ||
824 | \membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume} | |
825 | ||
826 | \func{void}{SetVolume}{\param{const wxString\& }{volume}} | |
827 | ||
828 | Sets the volume specifier. | |
829 | ||
830 | ||
831 | \membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath} | |
832 | ||
833 | \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}} | |
834 | ||
835 | \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}} | |
836 | ||
837 | \func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
838 | ||
839 | This function splits a full file name into components: the volume (with the | |
840 | first version) path (including the volume in the second version), the base name | |
841 | and the extension. Any of the output parameters ({\it volume}, {\it path}, | |
842 | {\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the | |
843 | value of a particular component. Also, {\it fullpath} may be empty on entry. | |
844 | ||
845 | On return, {\it path} contains the file path (without the trailing separator), | |
846 | {\it name} contains the file name and {\it ext} contains the file extension | |
847 | without leading dot. All three of them may be empty if the corresponding | |
848 | component is. The old contents of the strings pointed to by these parameters | |
849 | will be overwritten in any case (if the pointers are not {\tt NULL}). | |
850 | ||
851 | Note that for a filename ``foo.'' the extension is present, as indicated by the | |
852 | trailing dot, but empty. If you need to cope with such cases, you should use | |
853 | \arg{hasExt} instead of relying on testing whether \arg{ext} is empty or not. | |
854 | ||
855 | ||
856 | \membersection{wxFileName::SplitVolume}\label{wxfilenamesplitvolume} | |
857 | ||
858 | \func{static void}{SplitVolume}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} | |
859 | ||
860 | Splits the given \arg{fullpath} into the volume part (which may be empty) and | |
861 | the pure path part, not containing any volume. | |
862 | ||
863 | \wxheading{See also} | |
864 | ||
865 | \helpref{SplitPath}{wxfilenamesplitpath} | |
866 | ||
867 | ||
868 | \membersection{wxFileName::Touch}\label{wxfilenametouch} | |
869 | ||
870 | \func{bool}{Touch}{\void} | |
871 | ||
872 | Sets the access and modification times to the current moment. | |
873 | ||
874 | ||
875 | \membersection{wxFileName::operator=}\label{wxfilenameoperatorassign} | |
876 | ||
877 | \func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}} | |
878 | ||
879 | \func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}} | |
880 | ||
881 | Assigns the new value to this filename object. | |
882 | ||
883 | ||
884 | \membersection{wxFileName::operator==}\label{wxfilenameoperatorequal} | |
885 | ||
886 | \constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}} | |
887 | ||
888 | \constfunc{bool operator}{operator==}{\param{const wxString\& }{filename}} | |
889 | ||
890 | Returns {\tt true} if the filenames are equal. The string {\it filenames} is | |
891 | interpreted as a path in the native filename format. | |
892 | ||
893 | ||
894 | \membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal} | |
895 | ||
896 | \constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}} | |
897 | ||
898 | \constfunc{bool operator}{operator!=}{\param{const wxString\& }{filename}} | |
899 | ||
900 | Returns {\tt true} if the filenames are different. The string {\it filenames} | |
901 | is interpreted as a path in the native filename format. | |
902 |