interface/wx/filefn.h

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