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