interface/filefn.h

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