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