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