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