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