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 /** @ingroup 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     @header{wx/filefn.h}
 181 */
 182 void wxDos2UnixFilename(wxChar* s);
 183
 184 /**
 185     @warning This function is deprecated, use wxFileName instead.
 186
 187     Converts a Unix to a DOS filename by replacing forward slashes with
 188     backslashes.
 189
 190     @header{wx/filefn.h}
 191 */
 192 void wxUnix2DosFilename(wxChar* s);
 193
 194 /**
 195     Returns @true if @a dirname exists and is a directory.
 196
 197     @header{wx/filefn.h}
 198 */
 199 bool wxDirExists(const wxString& dirname);
 200
 201 /**
 202     @warning This function is obsolete, please use wxFileName::SplitPath()
 203              instead.
 204
 205     This function splits a full file name into components: the path (including
 206     possible disk/drive specification under Windows), the base name, and the
 207     extension. Any of the output parameters (@a path, @a name or @a ext) may be
 208     @NULL if you are not interested in the value of a particular component.
 209
 210     wxSplitPath() will correctly handle filenames with both DOS and Unix path
 211     separators under Windows, however it will not consider backslashes as path
 212     separators under Unix (where backslash is a valid character in a filename).
 213
 214     On entry, @a fullname should be non-@NULL (it may be empty though).
 215
 216     On return, @a path contains the file path (without the trailing separator),
 217     @a name contains the file name and @c ext contains the file extension
 218     without leading dot. All three of them may be empty if the corresponding
 219     component is. The old contents of the strings pointed to by these
 220     parameters will be overwritten in any case (if the pointers are not @NULL).
 221
 222     @header{wx/filefn.h}
 223 */
 224 void wxSplitPath(const wxString& fullname,
 225                   wxString* path,
 226                   wxString* name,
 227                   wxString* ext);
 228
 229 /**
 230     Returns time of last modification of given file.
 231
 232     The function returns <tt>(time_t)-1</tt> if an error occurred (e.g. file
 233     not found).
 234
 235     @header{wx/filefn.h}
 236 */
 237 time_t wxFileModificationTime(const wxString& filename);
 238
 239 /**
 240     Renames @a file1 to @e file2, returning @true if successful.
 241
 242     If @a overwrite parameter is @true (default), the destination file is
 243     overwritten if it exists, but if @a overwrite is @false, the functions
 244     fails in this case.
 245
 246     @header{wx/filefn.h}
 247 */
 248 bool wxRenameFile(const wxString& file1,
 249                    const wxString& file2,
 250                    bool overwrite = true);
 251
 252 /**
 253     Copies @a file1 to @e file2, returning @true if successful. If @a overwrite
 254     parameter is @true (default), the destination file is overwritten if it
 255     exists, but if @a overwrite is @false, the functions fails in this case.
 256
 257     This function supports resources forks under Mac OS.
 258
 259     @header{wx/filefn.h}
 260 */
 261 bool wxCopyFile(const wxString& file1,
 262                  const wxString& file2,
 263                  bool overwrite = true);
 264
 265 /**
 266     Returns @true if the file exists and is a plain file.
 267
 268     @header{wx/filefn.h}
 269 */
 270 bool wxFileExists(const wxString& filename);
 271
 272 /**
 273     Returns @true if the @a pattern matches the @e text; if @a dot_special is
 274     @true, filenames beginning with a dot are not matched with wildcard
 275     characters.
 276
 277     @see wxIsWild()
 278
 279     @header{wx/filefn.h}
 280 */
 281 bool wxMatchWild(const wxString& pattern,
 282                   const wxString& text,
 283                   bool dot_special);
 284
 285 /**
 286     @warning This function is deprecated, use wxGetCwd() instead.
 287
 288     Copies the current working directory into the buffer if supplied, or copies
 289     the working directory into new storage (which you must delete yourself) if
 290     the buffer is @NULL.
 291
 292     @a sz is the size of the buffer if supplied.
 293
 294     @header{wx/filefn.h}
 295 */
 296 wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000);
 297
 298 /**
 299     Returns the directory part of the filename.
 300
 301     @header{wx/filefn.h}
 302 */
 303 wxString wxPathOnly(const wxString& path);
 304
 305 /**
 306     Returns @true if the pattern contains wildcards.
 307
 308     @see wxMatchWild()
 309
 310     @header{wx/filefn.h}
 311 */
 312 bool wxIsWild(const wxString& pattern);
 313
 314 /**
 315     Returns @true if the argument is an absolute filename, i.e. with a slash
 316     or drive name at the beginning.
 317
 318     @header{wx/filefn.h}
 319 */
 320 bool wxIsAbsolutePath(const wxString& filename);
 321
 322 /**
 323     Returns a string containing the current (or working) directory.
 324
 325     @header{wx/filefn.h}
 326 */
 327 wxString wxGetCwd();
 328
 329 /**
 330     Sets the current working directory, returning @true if the operation
 331     succeeded. Under MS Windows, the current drive is also changed if @a dir
 332     contains a drive specification.
 333
 334     @header{wx/filefn.h}
 335 */
 336 bool wxSetWorkingDirectory(const wxString& dir);
 337
 338 /**
 339     Concatenates @a file1 and @a file2 to @e file3, returning @true if
 340     successful.
 341
 342     @header{wx/filefn.h}
 343 */
 344 bool wxConcatFiles(const wxString& file1,
 345                     const wxString& file2,
 346                     const wxString& file3);
 347
 348 /**
 349     Removes @e file, returning @true if successful.
 350
 351     @header{wx/filefn.h}
 352 */
 353 bool wxRemoveFile(const wxString& file);
 354
 355 /**
 356     Makes the directory @a dir, returning @true if successful.
 357
 358     @a perm is the access mask for the directory for the systems on which it is
 359     supported (Unix) and doesn't have any effect on the other ones.
 360
 361     @header{wx/filefn.h}
 362 */
 363 bool wxMkdir(const wxString& dir, int perm = 0777);
 364
 365 /**
 366     Removes the directory @a dir, returning @true if successful. Does not work
 367     under VMS.
 368
 369     The @a flags parameter is reserved for future use.
 370
 371     @note There is also a wxRmDir() function which simply wraps the standard
 372           POSIX @c rmdir() function and so return an integer error code instead
 373           of a boolean value (but otherwise is currently identical to
 374           wxRmdir()), don't confuse these two functions.
 375
 376     @header{wx/filefn.h}
 377 */
 378 bool wxRmdir(const wxString& dir, int flags = 0);
 379
 380 /**
 381     Returns the next file that matches the path passed to wxFindFirstFile().
 382
 383     See wxFindFirstFile() for an example.
 384
 385     @header{wx/filefn.h}
 386 */
 387 wxString wxFindNextFile();
 388
 389 /**
 390     This function does directory searching; returns the first file that matches
 391     the path @a spec, or the empty string. Use wxFindNextFile() to get the next
 392     matching file. Neither will report the current directory "." or the parent
 393     directory "..".
 394
 395     @warning As of 2.5.2, these functions are not thread-safe! (they use static
 396              variables). You probably want to use wxDir::GetFirst() or
 397              wxDirTraverser instead.
 398
 399     @a spec may contain wildcards.
 400
 401     @a flags may be wxDIR for restricting the query to directories, wxFILE for
 402     files or zero for either.
 403
 404     For example:
 405
 406     @code
 407     wxString f = wxFindFirstFile("/home/project/*.*");
 408     while ( !f.empty() )
 409     {
 410         ...
 411         f = wxFindNextFile();
 412     }
 413     @endcode
 414
 415     @header{wx/filefn.h}
 416 */
 417 wxString wxFindFirstFile(const wxString& spec, int flags = 0);
 418
 419 /**
 420     File kind enumerations returned from wxGetFileKind().
 421
 422     @header{wx/filefn.h}
 423 */
 424 enum wxFileKind
 425 {
 426     wxFILE_KIND_UNKNOWN,  ///< Unknown file kind, or unable to determine
 427     wxFILE_KIND_DISK,     ///< A file supporting seeking to arbitrary offsets
 428     wxFILE_KIND_TERMINAL, ///< A tty
 429     wxFILE_KIND_PIPE      ///< A pipe
 430 };
 431
 432 //@}
 433
 434 /** @ingroup group_funcmacro_file */
 435 //@{
 436 /**
 437     Returns the type of an open file. Possible return values are enumerations
 438     of ::wxFileKind.
 439
 440     @header{wx/filefn.h}
 441 */
 442 wxFileKind wxGetFileKind(int fd);
 443 wxFileKind wxGetFileKind(FILE* fp);
 444 //@}
 445
 446 /** @ingroup group_funcmacro_file */
 447 //@{
 448 /**
 449     @warning This function is obsolete, please use wxFileName::SplitPath()
 450              instead.
 451
 452     Returns the filename for a full path. The second form returns a pointer to
 453     temporary storage that should not be deallocated.
 454
 455     @header{wx/filefn.h}
 456 */
 457 wxString wxFileNameFromPath(const wxString& path);
 458 char* wxFileNameFromPath(char* path);
 459 //@}
 460
 461 /** @ingroup group_funcmacro_file */
 462 //@{
 463 /**
 464     @warning This function is obsolete, please use
 465              wxFileName::CreateTempFileName() instead.
 466
 467     @header{wx/filefn.h}
 468 */
 469 char* wxGetTempFileName(const wxString& prefix, char* buf = NULL);
 470 bool wxGetTempFileName(const wxString& prefix, wxString& buf);
 471 //@}
 472