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