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