1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: filefn.h 3 // Purpose: interface of wxPathList and file functions 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 @class wxPathList 10 11 The path list is a convenient way of storing a number of directories, and 12 when presented with a filename without a directory, searching for an 13 existing file in those directories. 14 15 Be sure to look also at wxStandardPaths if you only want to search files in 16 some standard paths. 17 18 @library{wxbase} 19 @category{file} 20 21 @see wxArrayString, wxStandardPaths, wxFileName 22 */ 23 class wxPathList : public wxArrayString 24 { 25 public: 26 /** 27 Standard constructor. 28 */ 29 wxPathList(); 30 31 /** 32 Constructs the object calling the Add() function. 33 */ 34 wxPathList(const wxArrayString& arr); 35 36 /** 37 Adds the given directory to the path list, if the @a path is not already in the list. 38 If the path cannot be normalized for some reason, it returns @false. 39 40 The @a path is always considered to be a directory but no existence checks will be 41 done on it (because if it doesn't exist, it could be created later and thus result a 42 valid path when FindValidPath() is called). 43 44 @note if the given path is relative, it won't be made absolute before adding it 45 (this is why FindValidPath() may return relative paths). 46 */ 47 bool Add(const wxString& path); 48 49 /** 50 Adds all elements of the given array as paths. 51 */ 52 void Add(const wxArrayString& arr); 53 54 /** 55 Finds the value of the given environment variable, and adds all paths 56 to the path list. 57 58 Useful for finding files in the @c PATH variable, for example. 59 */ 60 void AddEnvList(const wxString& env_variable); 61 62 /** 63 Given a full filename (with path), calls Add() with the path of the file. 64 */ 65 bool EnsureFileAccessible(const wxString& filename); 66 67 /** 68 Like FindValidPath() but this function always returns an absolute path 69 (eventually prepending the current working directory to the value returned 70 wxPathList::FindValidPath()) or an empty string. 71 */ 72 wxString FindAbsoluteValidPath(const wxString& file) const; 73 74 /** 75 Searches the given file in all paths stored in this class. 76 77 The first path which concatenated to the given string points to an existing 78 file (see wxFileExists()) is returned. 79 80 If the file wasn't found in any of the stored paths, an empty string is returned. 81 82 The given string must be a file name, eventually with a path prefix (if the path 83 prefix is absolute, only its name will be searched); i.e. it must not end with 84 a directory separator (see wxFileName::GetPathSeparator) otherwise an assertion 85 will fail. 86 87 The returned path may be relative to the current working directory. 88 89 Note in fact that wxPathList can be used to store both relative and absolute 90 paths so that if you added relative paths, then the current working directory 91 (see wxGetCwd() and wxSetWorkingDirectory()) may affect the value returned 92 by this function! 93 */ 94 wxString FindValidPath(const wxString& file) const; 95 }; 96 97 98 99 // ============================================================================ 100 // Global functions/macros 101 // ============================================================================ 102 103 /** @addtogroup group_funcmacro_file */ 104 //@{ 105 106 /** 107 A special return value of many wxWidgets classes to indicate that 108 an invalid offset was given. 109 */ 110 const int wxInvalidOffset = -1; 111 112 /** 113 The type used to store and provide byte offsets or byte sizes for files or streams. 114 115 This type is usually just a synonym for @c off_t but can be defined as 116 @c wxLongLong_t if @c wxHAS_HUGE_FILES is defined but @c off_t is only 32 117 bits. 118 */ 119 typedef off_t wxFileOffset; 120 121 /** 122 Under Unix this macro changes the current process umask to the given value, 123 unless it is equal to -1 in which case nothing is done, and restores it to 124 the original value on scope exit. It works by declaring a variable which 125 sets umask to @a mask in its constructor and restores it in its destructor. 126 Under other platforms this macro expands to nothing. 127 128 @header{wx/filefn.h} 129 */ 130 #define wxCHANGE_UMASK(mask) 131 132 /** 133 Returns the Windows directory under Windows; other platforms return an 134 empty string. 135 136 @header{wx/filefn.h} 137 */ 138 wxString wxGetOSDirectory(); 139 140 /** 141 Parses the @a wildCard, returning the number of filters. Returns 0 if none 142 or if there's a problem. 143 144 The arrays will contain an equal number of items found before the error. On 145 platforms where native dialogs handle only one filter per entry, entries in 146 arrays are automatically adjusted. @a wildCard is in the form: 147 148 @code 149 "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" 150 @endcode 151 152 @header{wx/filefn.h} 153 */ 154 int wxParseCommonDialogsFilter(const wxString& wildCard, 155 wxArrayString& descriptions, 156 wxArrayString& filters); 157 158 /** 159 Converts a DOS to a Unix filename by replacing backslashes with forward 160 slashes. 161 162 @deprecated 163 Construct a wxFileName with wxPATH_DOS and then use 164 wxFileName::GetFullPath(wxPATH_UNIX) instead. 165 166 @header{wx/filefn.h} 167 */ 168 void wxDos2UnixFilename(wxChar* s); 169 170 /** 171 Converts a Unix to a DOS filename by replacing forward slashes with 172 backslashes. 173 174 @deprecated 175 Construct a wxFileName with wxPATH_UNIX and then use 176 wxFileName::GetFullPath(wxPATH_DOS) instead. 177 178 @header{wx/filefn.h} 179 */ 180 void wxUnix2DosFilename(wxChar* s); 181 182 /** 183 Returns @true if @a dirname exists and is a directory. 184 185 @header{wx/filefn.h} 186 */ 187 bool wxDirExists(const wxString& dirname); 188 189 /** 190 @deprecated 191 This function is obsolete, please use wxFileName::SplitPath() instead. 192 193 This function splits a full file name into components: the path (including 194 possible disk/drive specification under Windows), the base name, and the 195 extension. Any of the output parameters (@a path, @a name or @a ext) may be 196 @NULL if you are not interested in the value of a particular component. 197 198 wxSplitPath() will correctly handle filenames with both DOS and Unix path 199 separators under Windows, however it will not consider backslashes as path 200 separators under Unix (where backslash is a valid character in a filename). 201 202 On entry, @a fullname should be non-@NULL (it may be empty though). 203 204 On return, @a path contains the file path (without the trailing separator), 205 @a name contains the file name and @c ext contains the file extension 206 without leading dot. All three of them may be empty if the corresponding 207 component is. The old contents of the strings pointed to by these 208 parameters will be overwritten in any case (if the pointers are not @NULL). 209 210 @header{wx/filefn.h} 211 */ 212 void wxSplitPath(const wxString& fullname, 213 wxString* path, 214 wxString* name, 215 wxString* ext); 216 217 /** 218 Returns time of last modification of given file. 219 220 The function returns <tt>(time_t)-1</tt> if an error occurred (e.g. file 221 not found). 222 223 @header{wx/filefn.h} 224 */ 225 time_t wxFileModificationTime(const wxString& filename); 226 227 /** 228 Renames @a oldpath to @e newpath, returning @true if successful. 229 230 If @a newpath is a directory, @a oldpath is moved into it (@a overwrite is 231 ignored in this case). Otherwise, if @a newpath is an existing file, it is 232 overwritten if @a overwrite is @true (default) and the function fails if @a 233 overwrite is @false. 234 235 @header{wx/filefn.h} 236 */ 237 bool wxRenameFile(const wxString& oldpath, 238 const wxString& newpath, 239 bool overwrite = true); 240 241 /** 242 Copies @a src to @e dest, returning @true if successful. If @a overwrite 243 parameter is @true (default), the destination file is overwritten if it 244 exists, but if @a overwrite is @false, the functions fails in this case. 245 246 This function supports resources forks under Mac OS. 247 248 @header{wx/filefn.h} 249 */ 250 bool wxCopyFile(const wxString& src, 251 const wxString& dest, 252 bool overwrite = true); 253 254 /** 255 Returns @true if the file exists and is a plain file. 256 257 @header{wx/filefn.h} 258 */ 259 bool wxFileExists(const wxString& filename); 260 261 /** 262 Returns @true if the @a pattern matches the @e text; if @a dot_special is 263 @true, filenames beginning with a dot are not matched with wildcard 264 characters. 265 266 @see wxIsWild() 267 268 @header{wx/filefn.h} 269 */ 270 bool wxMatchWild(const wxString& pattern, 271 const wxString& text, 272 bool dot_special); 273 274 /** 275 @deprecated This function is deprecated, use wxGetCwd() instead. 276 277 Copies the current working directory into the buffer if supplied, or copies 278 the working directory into new storage (which you must delete yourself) if 279 the buffer is @NULL. 280 281 @a sz is the size of the buffer if supplied. 282 283 @header{wx/filefn.h} 284 */ 285 wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000); 286 287 /** 288 Returns the directory part of the filename. 289 290 @header{wx/filefn.h} 291 */ 292 wxString wxPathOnly(const wxString& path); 293 294 /** 295 Returns @true if the pattern contains wildcards. 296 297 @see wxMatchWild() 298 299 @header{wx/filefn.h} 300 */ 301 bool wxIsWild(const wxString& pattern); 302 303 /** 304 Returns @true if the argument is an absolute filename, i.e.\ with a slash 305 or drive name at the beginning. 306 307 @header{wx/filefn.h} 308 */ 309 bool wxIsAbsolutePath(const wxString& filename); 310 311 /** 312 Returns a string containing the current (or working) directory. 313 314 @header{wx/filefn.h} 315 */ 316 wxString wxGetCwd(); 317 318 /** 319 Sets the current working directory, returning @true if the operation 320 succeeded. Under MS Windows, the current drive is also changed if @a dir 321 contains a drive specification. 322 323 @header{wx/filefn.h} 324 */ 325 bool wxSetWorkingDirectory(const wxString& dir); 326 327 /** 328 Concatenates @a src1 and @a src2 to @e dest, returning @true if 329 successful. 330 331 @header{wx/filefn.h} 332 */ 333 bool wxConcatFiles(const wxString& src1, 334 const wxString& src2, 335 const wxString& dest); 336 337 /** 338 Removes @e file, returning @true if successful. 339 340 @header{wx/filefn.h} 341 */ 342 bool wxRemoveFile(const wxString& file); 343 344 /** 345 File permission bit names. 346 347 We define these constants in wxWidgets because S_IREAD &c are not standard. 348 However, we do assume that the values correspond to the Unix umask bits. 349 */ 350 enum wxPosixPermissions 351 { 352 /// Standard POSIX names for these permission flags with "wx" prefix. 353 //@{ 354 wxS_IRUSR = 00400, 355 wxS_IWUSR = 00200, 356 wxS_IXUSR = 00100, 357 358 wxS_IRGRP = 00040, 359 wxS_IWGRP = 00020, 360 wxS_IXGRP = 00010, 361 362 wxS_IROTH = 00004, 363 wxS_IWOTH = 00002, 364 wxS_IXOTH = 00001, 365 //@} 366 367 /// Longer but more readable synonyms for the constants above. 368 //@{ 369 wxPOSIX_USER_READ = wxS_IRUSR, 370 wxPOSIX_USER_WRITE = wxS_IWUSR, 371 wxPOSIX_USER_EXECUTE = wxS_IXUSR, 372 373 wxPOSIX_GROUP_READ = wxS_IRGRP, 374 wxPOSIX_GROUP_WRITE = wxS_IWGRP, 375 wxPOSIX_GROUP_EXECUTE = wxS_IXGRP, 376 377 wxPOSIX_OTHERS_READ = wxS_IROTH, 378 wxPOSIX_OTHERS_WRITE = wxS_IWOTH, 379 wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH, 380 //@} 381 382 /// Default mode for the new files: allow reading/writing them to everybody but 383 /// the effective file mode will be set after ANDing this value with umask and 384 /// so won't include wxS_IW{GRP,OTH} for the default 022 umask value 385 wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \ 386 wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \ 387 wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE), 388 389 /// Default mode for the new directories (see wxFileName::Mkdir): allow 390 /// reading/writing/executing them to everybody, but just like wxS_DEFAULT 391 /// the effective directory mode will be set after ANDing this value with umask 392 wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \ 393 wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \ 394 wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE) 395 }; 396 397 /** 398 Makes the directory @a dir, returning @true if successful. 399 400 @a perm is the access mask for the directory for the systems on which it is 401 supported (Unix) and doesn't have any effect on the other ones. 402 403 @header{wx/filefn.h} 404 */ 405 bool wxMkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT); 406 407 /** 408 Removes the directory @a dir, returning @true if successful. Does not work 409 under VMS. 410 411 The @a flags parameter is reserved for future use. 412 413 @note There is also a wxRmDir() function which simply wraps the standard 414 POSIX @c rmdir() function and so return an integer error code instead 415 of a boolean value (but otherwise is currently identical to 416 wxRmdir()), don't confuse these two functions. 417 418 @header{wx/filefn.h} 419 */ 420 bool wxRmdir(const wxString& dir, int flags = 0); 421 422 /** 423 Returns the next file that matches the path passed to wxFindFirstFile(). 424 425 See wxFindFirstFile() for an example. 426 427 @header{wx/filefn.h} 428 */ 429 wxString wxFindNextFile(); 430 431 /** 432 This function does directory searching; returns the first file that matches 433 the path @a spec, or the empty string. Use wxFindNextFile() to get the next 434 matching file. Neither will report the current directory "." or the parent 435 directory "..". 436 437 @warning As of 2.5.2, these functions are not thread-safe! (they use static 438 variables). You probably want to use wxDir::GetFirst() or 439 wxDirTraverser instead. 440 441 @a spec may contain wildcards. 442 443 @a flags may be wxDIR for restricting the query to directories, wxFILE for 444 files or zero for either. 445 446 For example: 447 448 @code 449 wxString f = wxFindFirstFile("/home/project/*.*"); 450 while ( !f.empty() ) 451 { 452 ... 453 f = wxFindNextFile(); 454 } 455 @endcode 456 457 @header{wx/filefn.h} 458 */ 459 wxString wxFindFirstFile(const wxString& spec, int flags = 0); 460 461 /** 462 Parameter indicating how file offset should be interpreted. 463 464 This is used by wxFFile::Seek() and wxFile::Seek(). 465 466 @header{wx/filefn.h} 467 */ 468 enum wxSeekMode 469 { 470 wxFromStart, ///< Seek from the file beginning. 471 wxFromCurrent, ///< Seek from the current position. 472 wxFromEnd ///< Seek from end of the file. 473 }; 474 475 /** 476 File kind enumerations returned from wxGetFileKind(). 477 478 Also used by wxFFile::GetKind() and wxFile::GetKind(). 479 480 @header{wx/filefn.h} 481 */ 482 enum wxFileKind 483 { 484 wxFILE_KIND_UNKNOWN, ///< Unknown file kind, or unable to determine 485 wxFILE_KIND_DISK, ///< A file supporting seeking to arbitrary offsets 486 wxFILE_KIND_TERMINAL, ///< A tty 487 wxFILE_KIND_PIPE ///< A pipe 488 }; 489 490 //@} 491 492 /** @addtogroup group_funcmacro_file */ 493 //@{ 494 /** 495 Returns the type of an open file. Possible return values are enumerations 496 of ::wxFileKind. 497 498 @header{wx/filefn.h} 499 */ 500 wxFileKind wxGetFileKind(int fd); 501 wxFileKind wxGetFileKind(FILE* fp); 502 //@} 503 504 /** @addtogroup group_funcmacro_file */ 505 //@{ 506 /** 507 @deprecated 508 This function is obsolete, please use wxFileName::SplitPath() instead. 509 510 Returns the filename for a full path. The second form returns a pointer to 511 temporary storage that should not be deallocated. 512 513 @header{wx/filefn.h} 514 */ 515 wxString wxFileNameFromPath(const wxString& path); 516 char* wxFileNameFromPath(char* path); 517 //@} 518 519 /** @addtogroup group_funcmacro_file */ 520 //@{ 521 /** 522 @deprecated 523 This function is obsolete, please use wxFileName::CreateTempFileName() instead. 524 525 @header{wx/filefn.h} 526 */ 527 char* wxGetTempFileName(const wxString& prefix, char* buf = NULL); 528 bool wxGetTempFileName(const wxString& prefix, wxString& buf); 529 //@} 530 531