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{wxFileName}{DirName}{\param{const wxString\& }{dir}}
 269
 270 Returns the directory name.
 271
 272 \membersection{wxFileName::FileExists}\label{wxfilenamefileexists}
 273
 274 \constfunc{bool}{FileExists}{\void}
 275
 276 \func{static bool}{FileExists}{\param{const wxString\& }{file}}
 277
 278 Returns true if the file with this name exists.
 279
 280 \wxheading{See also}
 281
 282 \helpref{DirExists}{wxfilenamedirexists}
 283
 284 \membersection{wxFileName::FileName}\label{wxfilenamefilename}
 285
 286 \func{wxFileName}{FileName}{\param{const wxString\& }{file}}
 287
 288 Static pseudo constructors.
 289
 290 \membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd}
 291
 292 \func{wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}
 293
 294 Retrieves the value of the current working directory on the specified volume. If
 295 the volume is empty, the programs current working directory is returned for the
 296 current volume.
 297
 298 \wxheading{Return value}
 299
 300 The string containing the current working directory or an empty string on
 301 error.
 302
 303 \wxheading{See also}
 304
 305 \helpref{AssignCwd}{wxfilenameassigncwd}
 306
 307 \membersection{wxFileName::GetDirCount}\label{wxfilenamegetdircount}
 308
 309 \constfunc{size\_t}{GetDirCount}{\void}
 310
 311 Returns the number of directories in the file name.
 312
 313 \membersection{wxFileName::GetDirs}\label{wxfilenamegetdirs}
 314
 315 \constfunc{const wxArrayString\&}{GetDirs}{\void}
 316
 317 Returns the directories in string array form.
 318
 319 \membersection{wxFileName::GetExt}\label{wxfilenamegetext}
 320
 321 \constfunc{wxString}{GetExt}{\void}
 322
 323 Returns the file name extension.
 324
 325 \membersection{wxFileName::GetFormat}\label{wxfilenamegetformat}
 326
 327 \func{wxPathFormat}{GetFormat}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 328
 329 Returns the canonical path format for this platform.
 330
 331 \membersection{wxFileName::GetFullName}\label{wxfilenamegetfullname}
 332
 333 \constfunc{wxString}{GetFullName}{\void}
 334
 335 Returns the full name (including extension but excluding directories).
 336
 337 \membersection{wxFileName::GetFullPath}\label{wxfilenamegetfullpath}
 338
 339 \constfunc{wxString}{GetFullPath}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 340
 341 Returns the full path with name and extension.
 342
 343 \membersection{wxFileName::GetHomeDir}\label{wxfilenamegethomedir}
 344
 345 \func{wxString}{GetHomeDir}{\void}
 346
 347 Returns the home directory.
 348
 349 \membersection{wxFileName::GetLongPath}\label{wxfilenamegetlongpath}
 350
 351 \constfunc{wxString}{GetLongPath}{\void}
 352
 353 Return the long form of the path (returns identity on non-Windows platforms)
 354
 355 \membersection{wxFileName::GetModificationTime}\label{wxfilenamegetmodificationtime}
 356
 357 \constfunc{wxDateTime}{GetModificationTime}{\void}
 358
 359 Returns the last time the file was last modified.
 360
 361 \membersection{wxFileName::GetName}\label{wxfilenamegetname}
 362
 363 \constfunc{wxString}{GetName}{\void}
 364
 365 Returns the name part of the filename.
 366
 367 \membersection{wxFileName::GetPath}\label{wxfilenamegetpath}
 368
 369 \constfunc{wxString}{GetPath}{\param{int }{flags = $0$}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 370
 371 Returns the path part of the filename (without the name or extension). The
 372 possible flags values are:
 373
 374 \twocolwidtha{5cm}
 375 \begin{twocollist}\itemsep=0pt
 376 \twocolitem{{\bf wxPATH\_GET\_VOLUME}}{Return the path with the volume (does
 377 nothing for the filename formats without volumes)}
 378 \twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing
 379 separator, if this flag is not given there will be no separator at the end of
 380 the path.}
 381 \end{twocollist}
 382
 383 \membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator}
 384
 385 \func{wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 386
 387 Returns the usually used path separator for this format. For all formats but
 388 {\tt wxPATH\_DOS} there is only one path separator anyhow, but for DOS there
 389 are two of them and the native one, i.e. the backslash is returned by this
 390 method.
 391
 392 \wxheading{See also}
 393
 394 \helpref{GetPathSeparators}{wxfilenamegetpathseparators}
 395
 396 \membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators}
 397
 398 \func{wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 399
 400 Returns the string containing all the path separators for this format. For all
 401 formats but {\tt wxPATH\_DOS} this string contains only one character but for
 402 DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as
 403 separators.
 404
 405 \wxheading{See also}
 406
 407 \helpref{GetPathSeparator}{wxfilenamegetpathseparator}
 408
 409 \membersection{wxFileName::GetShortPath}\label{wxfilenamegetshortpath}
 410
 411 \constfunc{wxString}{GetShortPath}{\void}
 412
 413 Return the short form of the path (returns identity on non-Windows platforms).
 414
 415 \membersection{wxFileName::GetTimes}\label{wxfilenamegettimes}
 416
 417 \constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}
 418
 419 Returns the last access, last modification and creation times. The last access
 420 time is updated whenever the file is read or written (or executed in the case
 421 of Windows), last modification time is only changed when the file is written
 422 to. Finally, the creation time is indeed the time when the file was created
 423 under Windows and the inode change time under Unix (as it is impossible to
 424 retrieve the real file creation time there anyhow) which can also be changed
 425 by many operations after the file creation.
 426
 427 Any of the pointers may be {\tt NULL} if the corresponding time is not
 428 needed.
 429
 430 \wxheading{Return value}
 431
 432 {\tt true} on success, {\tt false} if we failed to retrieve the times.
 433
 434 \membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume}
 435
 436 \constfunc{wxString}{GetVolume}{\void}
 437
 438 Returns the string containing the volume for this file name, mepty if it
 439 doesn't have one or if the file system doesn't support volumes at all (for
 440 example, Unix).
 441
 442 \membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
 443
 444 \func{wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 445
 446 Returns the string separating the volume from the path for this format.
 447
 448 \membersection{wxFileName::HasExt}\label{wxfilenamehasext}
 449
 450 \constfunc{bool}{HasExt}{\void}
 451
 452 Returns true if an extension is present.
 453
 454 \membersection{wxFileName::HasName}\label{wxfilenamehasname}
 455
 456 \constfunc{bool}{HasName}{\void}
 457
 458 Returns true if a name is present.
 459
 460 \membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
 461
 462 \constfunc{bool}{HasVolume}{\void}
 463
 464 Returns true if a volume specifier is present.
 465
 466 \membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir}
 467
 468 \func{void}{InsertDir}{\param{int }{before}, \param{const wxString\& }{dir}}
 469
 470 Inserts a directory before the zero-based position in the directory list.
 471
 472 \membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute}
 473
 474 \func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 475
 476 Returns true if this filename is absolute.
 477
 478 \membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive}
 479
 480 \func{bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 481
 482 Returns true if the file names of this type are case-sensitive.
 483
 484 \membersection{wxFileName::IsOk}\label{wxfilenameisok}
 485
 486 \constfunc{bool}{IsOk}{\void}
 487
 488 Returns {\tt true} if the filename is valid, {\tt false} if it is not
 489 initialized yet. The assignment functions and
 490 \helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized,
 491 invalid state (the former only do it on failure).
 492
 493 \membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator}
 494
 495 \func{bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 496
 497 Returns {\tt true} if the char is a path separator for this format.
 498
 499 \membersection{wxFileName::IsRelative}\label{wxfilenameisrelative}
 500
 501 \func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 502
 503 Returns {\tt true} if this filename is not absolute.
 504
 505 \membersection{wxFileName::IsDir}\label{wxfilenameisdir}
 506
 507 \constfunc{bool}{IsDir}{\void}
 508
 509 Returns {\tt true} if this object represents a directory, {\tt false} otherwise
 510 (i.e. if it is a file). Note that this method doesn't test whether the
 511 directory or file really exists, you should use
 512 \helpref{DirExists}{wxfilenamedirexists} or
 513 \helpref{FileExists}{wxfilenamefileexists} for this.
 514
 515 \membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute}
 516
 517 \func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 518
 519 Make the file name absolute. This is a shortcut for
 520 {\tt \helpref{Normalize}{wxfilenamenormalize}(wxPATH\_NORM\_DOTS | wxPATH\_NORM\_ABSOLUTE | wxPATH\_NORM\_TILDE, cwd, format)}.
 521
 522 \wxheading{See also}
 523
 524 \helpref{MakeRelativeTo}{wxfilenamemakerelativeto},
 525 \helpref{Normalize}{wxfilenamenormalize},
 526 \helpref{IsAbsolute}{wxfilenameisabsolute}
 527
 528 \membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto}
 529
 530 \func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = ""}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 531
 532 This function tries to put this file name in a form relative to {\it pathBase}.
 533 In other words, it returns the file name which should be used to access this
 534 file if the current directory were {\it pathBase}.
 535
 536 \docparam{pathBase}{the directory to use as root, current directory is used by
 537 default}
 538
 539 \docparam{format}{the file name format, native by default}
 540
 541 \wxheading{Return value}
 542
 543 {\tt true} if the file name has been changed, {\tt false} if we failed to do
 544 anything with it (currently this only happens if the file name is on a volume
 545 different from the volume specified by {\it pathBase}).
 546
 547 \wxheading{See also}
 548
 549 \helpref{Normalize}{wxfilenamenormalize}
 550
 551 \membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
 552
 553 \func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}}
 554
 555 \func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}}
 556
 557 \docparam{dir}{the directory to create}
 558
 559 \docparam{parm}{the permissions for the newly created directory}
 560
 561 \docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag,
 562 try to create each directory in the path and also don't return an error
 563 if the target directory already exists.}
 564
 565 \wxheading{Return value}
 566
 567 Returns {\tt true} if the directory was successfully created, {\tt false}
 568 otherwise.
 569
 570 \membersection{wxFileName::Normalize}\label{wxfilenamenormalize}
 571
 572 \func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 573
 574 Normalize the path. With the default flags value, the path will be
 575 made absolute, without any ".." and "." and all environment
 576 variables will be expanded in it.
 577
 578 \docparam{flags}{The kind of normalization to do with the file name. It can be
 579 any or-combination of the following constants:
 580 \begin{twocollist}
 581 \twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values}
 582 \twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . and prepend cwd}
 583 \twocolitem{{\bf wxPATH\_NORM\_TILDE}}{Unix only: replace ~ and ~user}
 584 \twocolitem{{\bf wxPATH\_NORM\_CASE}}{if case insensitive => tolower}
 585 \twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute}
 586 \twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form}
 587 \twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags}
 588 \end{twocollist}
 589 }
 590
 591 \docparam{cwd}{If not empty, this directory will be used instead of current
 592 working directory in normalization.}
 593
 594 \docparam{format}{The file name format, native by default.}
 595
 596 \membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}
 597
 598 \func{void}{PrependDir}{\param{const wxString\& }{dir}}
 599
 600 Prepends a directory name.
 601
 602 \membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir}
 603
 604 \func{void}{RemoveDir}{\param{int }{pos}}
 605
 606 Removes a directory name.
 607
 608 \membersection{wxFileName::Rmdir}\label{wxfilenamermdir}
 609
 610 \func{bool}{Rmdir}{\void}
 611
 612 \func{static bool}{Rmdir}{\param{const wxString\& }{dir}}
 613
 614 Deletes the specified directory from the file system.
 615
 616 \membersection{wxFileName::SameAs}\label{wxfilenamesameas}
 617
 618 \constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 619
 620 Compares the filename using the rules of this platform.
 621
 622 \membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
 623
 624 \func{bool}{SetCwd}{\void}
 625
 626 \func{static bool}{SetCwd}{\param{const wxString\& }{cwd}}
 627
 628 Changes the current working directory.
 629
 630 \membersection{wxFileName::SetExt}\label{wxfilenamesetext}
 631
 632 \func{void}{SetExt}{\param{const wxString\& }{ext}}
 633
 634 Sets the extension of this file name.
 635
 636 \membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname}
 637
 638 \func{void}{SetFullName}{\param{const wxString\& }{fullname}}
 639
 640 The full name is the file name and extension (but without the path).
 641
 642 \membersection{wxFileName::SetName}\label{wxfilenamesetname}
 643
 644 \func{void}{SetName}{\param{const wxString\& }{name}}
 645
 646 Sets the name.
 647
 648 \membersection{wxFileName::SetTimes}\label{wxfilenamesettimes}
 649
 650 \func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}}
 651
 652 Sets the file creation and last access/modification times (any of the pointers may be NULL).
 653
 654 \membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume}
 655
 656 \func{void}{SetVolume}{\param{const wxString\& }{volume}}
 657
 658 Sets the volume specifier.
 659
 660 \membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath}
 661
 662 \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}}
 663
 664 \func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 665
 666 This function splits a full file name into components: the volume (with the
 667 first version) path (including the volume in the second version), the base name
 668 and the extension. Any of the output parameters ({\it volume}, {\it path},
 669 {\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the
 670 value of a particular component. Also, {\it fullpath} may be empty on entry.
 671
 672 On return, {\it path} contains the file path (without the trailing separator),
 673 {\it name} contains the file name and {\it ext} contains the file extension
 674 without leading dot. All three of them may be empty if the corresponding
 675 component is. The old contents of the strings pointed to by these parameters
 676 will be overwritten in any case (if the pointers are not {\tt NULL}).
 677
 678 \membersection{wxFileName::Touch}\label{wxfilenametouch}
 679
 680 \func{bool}{Touch}{\void}
 681
 682 Sets the access and modification times to the current moment.
 683
 684 \membersection{wxFileName::operator=}\label{wxfilenameoperatorassign}
 685
 686 \func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}}
 687
 688 \func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}}
 689
 690 Assigns the new value to this filename object.
 691
 692 \membersection{wxFileName::operator==}\label{wxfilenameoperatorequal}
 693
 694 \constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}}
 695
 696 \constfunc{bool operator}{operator==}{\param{const wxString\& }{filename}}
 697
 698 Returns {\tt true} if the filenames are equal. The string {\it filenames} is
 699 interpreted as a path in the native filename format.
 700
 701 \membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal}
 702
 703 \constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}}
 704
 705 \constfunc{bool operator}{operator!=}{\param{const wxString\& }{filename}}
 706
 707 Returns {\tt true} if the filenames are different. The string {\it filenames}
 708 is interpreted as a path in the native filename format.
 709