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