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::GetShortPath}\label{wxfilenamegetshortpath}
 464
 465 \constfunc{wxString}{GetShortPath}{\void}
 466
 467 Return the short form of the path (returns identity on non-Windows platforms).
 468
 469
 470 \membersection{wxFileName::GetTimes}\label{wxfilenamegettimes}
 471
 472 \constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}
 473
 474 Returns the last access, last modification and creation times. The last access
 475 time is updated whenever the file is read or written (or executed in the case
 476 of Windows), last modification time is only changed when the file is written
 477 to. Finally, the creation time is indeed the time when the file was created
 478 under Windows and the inode change time under Unix (as it is impossible to
 479 retrieve the real file creation time there anyhow) which can also be changed
 480 by many operations after the file creation.
 481
 482 Any of the pointers may be {\tt NULL} if the corresponding time is not
 483 needed.
 484
 485 \wxheading{Return value}
 486
 487 {\tt true} on success, {\tt false} if we failed to retrieve the times.
 488
 489
 490 \membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume}
 491
 492 \constfunc{wxString}{GetVolume}{\void}
 493
 494 Returns the string containing the volume for this file name, mepty if it
 495 doesn't have one or if the file system doesn't support volumes at all (for
 496 example, Unix).
 497
 498
 499 \membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
 500
 501 \func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 502
 503 Returns the string separating the volume from the path for this format.
 504
 505
 506 \membersection{wxFileName::HasExt}\label{wxfilenamehasext}
 507
 508 \constfunc{bool}{HasExt}{\void}
 509
 510 Returns {\tt true} if an extension is present.
 511
 512
 513 \membersection{wxFileName::HasName}\label{wxfilenamehasname}
 514
 515 \constfunc{bool}{HasName}{\void}
 516
 517 Returns {\tt true} if a name is present.
 518
 519
 520 \membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
 521
 522 \constfunc{bool}{HasVolume}{\void}
 523
 524 Returns {\tt true} if a volume specifier is present.
 525
 526
 527 \membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir}
 528
 529 \func{void}{InsertDir}{\param{int }{before}, \param{const wxString\& }{dir}}
 530
 531 Inserts a directory component before the zero-based position in the directory
 532 list. Please see \helpref{AppendDir}{wxfilenameappenddir} for important notes.
 533
 534
 535 \membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute}
 536
 537 \func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 538
 539 Returns {\tt true} if this filename is absolute.
 540
 541
 542 \membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive}
 543
 544 \func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 545
 546 Returns {\tt true} if the file names of this type are case-sensitive.
 547
 548
 549 \membersection{wxFileName::IsOk}\label{wxfilenameisok}
 550
 551 \constfunc{bool}{IsOk}{\void}
 552
 553 Returns {\tt true} if the filename is valid, {\tt false} if it is not
 554 initialized yet. The assignment functions and
 555 \helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized,
 556 invalid state (the former only do it on failure).
 557
 558
 559 \membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator}
 560
 561 \func{static bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 562
 563 Returns {\tt true} if the char is a path separator for this format.
 564
 565
 566 \membersection{wxFileName::IsRelative}\label{wxfilenameisrelative}
 567
 568 \func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 569
 570 Returns {\tt true} if this filename is not absolute.
 571
 572
 573 \membersection{wxFileName::IsDir}\label{wxfilenameisdir}
 574
 575 \constfunc{bool}{IsDir}{\void}
 576
 577 Returns {\tt true} if this object represents a directory, {\tt false} otherwise
 578 (i.e. if it is a file). Note that this method doesn't test whether the
 579 directory or file really exists, you should use
 580 \helpref{DirExists}{wxfilenamedirexists} or
 581 \helpref{FileExists}{wxfilenamefileexists} for this.
 582
 583
 584 \membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute}
 585
 586 \func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 587
 588 Make the file name absolute. This is a shortcut for
 589 {\tt \helpref{Normalize}{wxfilenamenormalize}(wxPATH\_NORM\_DOTS | wxPATH\_NORM\_ABSOLUTE | wxPATH\_NORM\_TILDE, cwd, format)}.
 590
 591 \wxheading{See also}
 592
 593 \helpref{MakeRelativeTo}{wxfilenamemakerelativeto},
 594 \helpref{Normalize}{wxfilenamenormalize},
 595 \helpref{IsAbsolute}{wxfilenameisabsolute}
 596
 597
 598 \membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto}
 599
 600 \func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 601
 602 This function tries to put this file name in a form relative to {\it pathBase}.
 603 In other words, it returns the file name which should be used to access this
 604 file if the current directory were {\it pathBase}.
 605
 606 \docparam{pathBase}{the directory to use as root, current directory is used by
 607 default}
 608
 609 \docparam{format}{the file name format, native by default}
 610
 611 \wxheading{Return value}
 612
 613 {\tt true} if the file name has been changed, {\tt false} if we failed to do
 614 anything with it (currently this only happens if the file name is on a volume
 615 different from the volume specified by {\it pathBase}).
 616
 617 \wxheading{See also}
 618
 619 \helpref{Normalize}{wxfilenamenormalize}
 620
 621
 622 \membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
 623
 624 \func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}}
 625
 626 \func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}}
 627
 628 \docparam{dir}{the directory to create}
 629
 630 \docparam{parm}{the permissions for the newly created directory}
 631
 632 \docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag,
 633 try to create each directory in the path and also don't return an error
 634 if the target directory already exists.}
 635
 636 \wxheading{Return value}
 637
 638 Returns {\tt true} if the directory was successfully created, {\tt false}
 639 otherwise.
 640
 641
 642 \membersection{wxFileName::Normalize}\label{wxfilenamenormalize}
 643
 644 \func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 645
 646 Normalize the path. With the default flags value, the path will be
 647 made absolute, without any ".." and "." and all environment
 648 variables will be expanded in it.
 649
 650 \docparam{flags}{The kind of normalization to do with the file name. It can be
 651 any or-combination of the following constants:
 652
 653 \begin{twocollist}
 654 \twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values}
 655 \twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . and prepend cwd}
 656 \twocolitem{{\bf wxPATH\_NORM\_TILDE}}{Unix only: replace ~ and ~user}
 657 \twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to tolower case}
 658 \twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute}
 659 \twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form}
 660 \twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)}
 661 \twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}}
 662 \end{twocollist}
 663 }%
 664
 665 \docparam{cwd}{If not empty, this directory will be used instead of current
 666 working directory in normalization.}
 667
 668 \docparam{format}{The file name format, native by default.}
 669
 670
 671 \membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}
 672
 673 \func{void}{PrependDir}{\param{const wxString\& }{dir}}
 674
 675 Prepends a directory to the file path. Please see
 676 \helpref{AppendDir}{wxfilenameappenddir} for important notes.
 677
 678
 679
 680 \membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir}
 681
 682 \func{void}{RemoveDir}{\param{int }{pos}}
 683
 684 Removes a directory name.
 685
 686
 687 \membersection{wxFileName::Rmdir}\label{wxfilenamermdir}
 688
 689 \func{bool}{Rmdir}{\void}
 690
 691 \func{static bool}{Rmdir}{\param{const wxString\& }{dir}}
 692
 693 Deletes the specified directory from the file system.
 694
 695
 696 \membersection{wxFileName::SameAs}\label{wxfilenamesameas}
 697
 698 \constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 699
 700 Compares the filename using the rules of this platform.
 701
 702
 703 \membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
 704
 705 \func{bool}{SetCwd}{\void}
 706
 707 \func{static bool}{SetCwd}{\param{const wxString\& }{cwd}}
 708
 709 Changes the current working directory.
 710
 711
 712 \membersection{wxFileName::SetExt}\label{wxfilenamesetext}
 713
 714 \func{void}{SetExt}{\param{const wxString\& }{ext}}
 715
 716 Sets the extension of this file name.
 717
 718
 719 \membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname}
 720
 721 \func{void}{SetFullName}{\param{const wxString\& }{fullname}}
 722
 723 The full name is the file name and extension (but without the path).
 724
 725
 726 \membersection{wxFileName::SetName}\label{wxfilenamesetname}
 727
 728 \func{void}{SetName}{\param{const wxString\& }{name}}
 729
 730 Sets the name.
 731
 732
 733 \membersection{wxFileName::SetTimes}\label{wxfilenamesettimes}
 734
 735 \func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}}
 736
 737 Sets the file creation and last access/modification times (any of the pointers may be NULL).
 738
 739
 740 \membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume}
 741
 742 \func{void}{SetVolume}{\param{const wxString\& }{volume}}
 743
 744 Sets the volume specifier.
 745
 746
 747 \membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath}
 748
 749 \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}}
 750
 751 \func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 752
 753 This function splits a full file name into components: the volume (with the
 754 first version) path (including the volume in the second version), the base name
 755 and the extension. Any of the output parameters ({\it volume}, {\it path},
 756 {\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the
 757 value of a particular component. Also, {\it fullpath} may be empty on entry.
 758
 759 On return, {\it path} contains the file path (without the trailing separator),
 760 {\it name} contains the file name and {\it ext} contains the file extension
 761 without leading dot. All three of them may be empty if the corresponding
 762 component is. The old contents of the strings pointed to by these parameters
 763 will be overwritten in any case (if the pointers are not {\tt NULL}).
 764
 765
 766 \membersection{wxFileName::Touch}\label{wxfilenametouch}
 767
 768 \func{bool}{Touch}{\void}
 769
 770 Sets the access and modification times to the current moment.
 771
 772
 773 \membersection{wxFileName::operator=}\label{wxfilenameoperatorassign}
 774
 775 \func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}}
 776
 777 \func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}}
 778
 779 Assigns the new value to this filename object.
 780
 781
 782 \membersection{wxFileName::operator==}\label{wxfilenameoperatorequal}
 783
 784 \constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}}
 785
 786 \constfunc{bool operator}{operator==}{\param{const wxString\& }{filename}}
 787
 788 Returns {\tt true} if the filenames are equal. The string {\it filenames} is
 789 interpreted as a path in the native filename format.
 790
 791
 792 \membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal}
 793
 794 \constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}}
 795
 796 \constfunc{bool operator}{operator!=}{\param{const wxString\& }{filename}}
 797
 798 Returns {\tt true} if the filenames are different. The string {\it filenames}
 799 is interpreted as a path in the native filename format.
 800