interface/filefn.h

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