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 = {\tt wxPATH\_GET\_VOLUME}}, \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), otherwise the path without
 390 volume part is returned.}
 391 \twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing
 392 separator, if this flag is not given there will be no separator at the end of
 393 the path.}
 394 \end{twocollist}
 395
 396 \membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator}
 397
 398 \func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 399
 400 Returns the usually used path separator for this format. For all formats but
 401 {\tt wxPATH\_DOS} there is only one path separator anyhow, but for DOS there
 402 are two of them and the native one, i.e. the backslash is returned by this
 403 method.
 404
 405 \wxheading{See also}
 406
 407 \helpref{GetPathSeparators}{wxfilenamegetpathseparators}
 408
 409 \membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators}
 410
 411 \func{static wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 412
 413 Returns the string containing all the path separators for this format. For all
 414 formats but {\tt wxPATH\_DOS} this string contains only one character but for
 415 DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as
 416 separators.
 417
 418 \wxheading{See also}
 419
 420 \helpref{GetPathSeparator}{wxfilenamegetpathseparator}
 421
 422 \membersection{wxFileName::GetShortPath}\label{wxfilenamegetshortpath}
 423
 424 \constfunc{wxString}{GetShortPath}{\void}
 425
 426 Return the short form of the path (returns identity on non-Windows platforms).
 427
 428 \membersection{wxFileName::GetTimes}\label{wxfilenamegettimes}
 429
 430 \constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}
 431
 432 Returns the last access, last modification and creation times. The last access
 433 time is updated whenever the file is read or written (or executed in the case
 434 of Windows), last modification time is only changed when the file is written
 435 to. Finally, the creation time is indeed the time when the file was created
 436 under Windows and the inode change time under Unix (as it is impossible to
 437 retrieve the real file creation time there anyhow) which can also be changed
 438 by many operations after the file creation.
 439
 440 Any of the pointers may be {\tt NULL} if the corresponding time is not
 441 needed.
 442
 443 \wxheading{Return value}
 444
 445 {\tt true} on success, {\tt false} if we failed to retrieve the times.
 446
 447 \membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume}
 448
 449 \constfunc{wxString}{GetVolume}{\void}
 450
 451 Returns the string containing the volume for this file name, mepty if it
 452 doesn't have one or if the file system doesn't support volumes at all (for
 453 example, Unix).
 454
 455 \membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
 456
 457 \func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 458
 459 Returns the string separating the volume from the path for this format.
 460
 461 \membersection{wxFileName::HasExt}\label{wxfilenamehasext}
 462
 463 \constfunc{bool}{HasExt}{\void}
 464
 465 Returns {\tt true} if an extension is present.
 466
 467 \membersection{wxFileName::HasName}\label{wxfilenamehasname}
 468
 469 \constfunc{bool}{HasName}{\void}
 470
 471 Returns {\tt true} if a name is present.
 472
 473 \membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
 474
 475 \constfunc{bool}{HasVolume}{\void}
 476
 477 Returns {\tt true} if a volume specifier is present.
 478
 479 \membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir}
 480
 481 \func{void}{InsertDir}{\param{int }{before}, \param{const wxString\& }{dir}}
 482
 483 Inserts a directory before the zero-based position in the directory list.
 484
 485 \membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute}
 486
 487 \func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 488
 489 Returns {\tt true} if this filename is absolute.
 490
 491 \membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive}
 492
 493 \func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 494
 495 Returns {\tt true} if the file names of this type are case-sensitive.
 496
 497 \membersection{wxFileName::IsOk}\label{wxfilenameisok}
 498
 499 \constfunc{bool}{IsOk}{\void}
 500
 501 Returns {\tt true} if the filename is valid, {\tt false} if it is not
 502 initialized yet. The assignment functions and
 503 \helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized,
 504 invalid state (the former only do it on failure).
 505
 506 \membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator}
 507
 508 \func{static bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 509
 510 Returns {\tt true} if the char is a path separator for this format.
 511
 512 \membersection{wxFileName::IsRelative}\label{wxfilenameisrelative}
 513
 514 \func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 515
 516 Returns {\tt true} if this filename is not absolute.
 517
 518 \membersection{wxFileName::IsDir}\label{wxfilenameisdir}
 519
 520 \constfunc{bool}{IsDir}{\void}
 521
 522 Returns {\tt true} if this object represents a directory, {\tt false} otherwise
 523 (i.e. if it is a file). Note that this method doesn't test whether the
 524 directory or file really exists, you should use
 525 \helpref{DirExists}{wxfilenamedirexists} or
 526 \helpref{FileExists}{wxfilenamefileexists} for this.
 527
 528 \membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute}
 529
 530 \func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 531
 532 Make the file name absolute. This is a shortcut for
 533 {\tt \helpref{Normalize}{wxfilenamenormalize}(wxPATH\_NORM\_DOTS | wxPATH\_NORM\_ABSOLUTE | wxPATH\_NORM\_TILDE, cwd, format)}.
 534
 535 \wxheading{See also}
 536
 537 \helpref{MakeRelativeTo}{wxfilenamemakerelativeto},
 538 \helpref{Normalize}{wxfilenamenormalize},
 539 \helpref{IsAbsolute}{wxfilenameisabsolute}
 540
 541 \membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto}
 542
 543 \func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 544
 545 This function tries to put this file name in a form relative to {\it pathBase}.
 546 In other words, it returns the file name which should be used to access this
 547 file if the current directory were {\it pathBase}.
 548
 549 \docparam{pathBase}{the directory to use as root, current directory is used by
 550 default}
 551
 552 \docparam{format}{the file name format, native by default}
 553
 554 \wxheading{Return value}
 555
 556 {\tt true} if the file name has been changed, {\tt false} if we failed to do
 557 anything with it (currently this only happens if the file name is on a volume
 558 different from the volume specified by {\it pathBase}).
 559
 560 \wxheading{See also}
 561
 562 \helpref{Normalize}{wxfilenamenormalize}
 563
 564 \membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
 565
 566 \func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}}
 567
 568 \func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}}
 569
 570 \docparam{dir}{the directory to create}
 571
 572 \docparam{parm}{the permissions for the newly created directory}
 573
 574 \docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag,
 575 try to create each directory in the path and also don't return an error
 576 if the target directory already exists.}
 577
 578 \wxheading{Return value}
 579
 580 Returns {\tt true} if the directory was successfully created, {\tt false}
 581 otherwise.
 582
 583 \membersection{wxFileName::Normalize}\label{wxfilenamenormalize}
 584
 585 \func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 586
 587 Normalize the path. With the default flags value, the path will be
 588 made absolute, without any ".." and "." and all environment
 589 variables will be expanded in it.
 590
 591 \docparam{flags}{The kind of normalization to do with the file name. It can be
 592 any or-combination of the following constants:
 593 \begin{twocollist}
 594 \twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values}
 595 \twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . and prepend cwd}
 596 \twocolitem{{\bf wxPATH\_NORM\_TILDE}}{Unix only: replace ~ and ~user}
 597 \twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to tolower case}
 598 \twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute}
 599 \twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form}
 600 \twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}}
 601 \end{twocollist}
 602 }
 603
 604 \docparam{cwd}{If not empty, this directory will be used instead of current
 605 working directory in normalization.}
 606
 607 \docparam{format}{The file name format, native by default.}
 608
 609 \membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}
 610
 611 \func{void}{PrependDir}{\param{const wxString\& }{dir}}
 612
 613 Prepends a directory name.
 614
 615 \membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir}
 616
 617 \func{void}{RemoveDir}{\param{int }{pos}}
 618
 619 Removes a directory name.
 620
 621 \membersection{wxFileName::Rmdir}\label{wxfilenamermdir}
 622
 623 \func{bool}{Rmdir}{\void}
 624
 625 \func{static bool}{Rmdir}{\param{const wxString\& }{dir}}
 626
 627 Deletes the specified directory from the file system.
 628
 629 \membersection{wxFileName::SameAs}\label{wxfilenamesameas}
 630
 631 \constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 632
 633 Compares the filename using the rules of this platform.
 634
 635 \membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
 636
 637 \func{bool}{SetCwd}{\void}
 638
 639 \func{static bool}{SetCwd}{\param{const wxString\& }{cwd}}
 640
 641 Changes the current working directory.
 642
 643 \membersection{wxFileName::SetExt}\label{wxfilenamesetext}
 644
 645 \func{void}{SetExt}{\param{const wxString\& }{ext}}
 646
 647 Sets the extension of this file name.
 648
 649 \membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname}
 650
 651 \func{void}{SetFullName}{\param{const wxString\& }{fullname}}
 652
 653 The full name is the file name and extension (but without the path).
 654
 655 \membersection{wxFileName::SetName}\label{wxfilenamesetname}
 656
 657 \func{void}{SetName}{\param{const wxString\& }{name}}
 658
 659 Sets the name.
 660
 661 \membersection{wxFileName::SetTimes}\label{wxfilenamesettimes}
 662
 663 \func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}}
 664
 665 Sets the file creation and last access/modification times (any of the pointers may be NULL).
 666
 667 \membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume}
 668
 669 \func{void}{SetVolume}{\param{const wxString\& }{volume}}
 670
 671 Sets the volume specifier.
 672
 673 \membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath}
 674
 675 \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}}
 676
 677 \func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 678
 679 This function splits a full file name into components: the volume (with the
 680 first version) path (including the volume in the second version), the base name
 681 and the extension. Any of the output parameters ({\it volume}, {\it path},
 682 {\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the
 683 value of a particular component. Also, {\it fullpath} may be empty on entry.
 684
 685 On return, {\it path} contains the file path (without the trailing separator),
 686 {\it name} contains the file name and {\it ext} contains the file extension
 687 without leading dot. All three of them may be empty if the corresponding
 688 component is. The old contents of the strings pointed to by these parameters
 689 will be overwritten in any case (if the pointers are not {\tt NULL}).
 690
 691 \membersection{wxFileName::Touch}\label{wxfilenametouch}
 692
 693 \func{bool}{Touch}{\void}
 694
 695 Sets the access and modification times to the current moment.
 696
 697 \membersection{wxFileName::operator=}\label{wxfilenameoperatorassign}
 698
 699 \func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}}
 700
 701 \func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}}
 702
 703 Assigns the new value to this filename object.
 704
 705 \membersection{wxFileName::operator==}\label{wxfilenameoperatorequal}
 706
 707 \constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}}
 708
 709 \constfunc{bool operator}{operator==}{\param{const wxString\& }{filename}}
 710
 711 Returns {\tt true} if the filenames are equal. The string {\it filenames} is
 712 interpreted as a path in the native filename format.
 713
 714 \membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal}
 715
 716 \constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}}
 717
 718 \constfunc{bool operator}{operator!=}{\param{const wxString\& }{filename}}
 719
 720 Returns {\tt true} if the filenames are different. The string {\it filenames}
 721 is interpreted as a path in the native filename format.
 722