]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/filefn.h
9659221bdb21c49402590291d069811238d2c5fe
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPathList and file functions
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
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.
16 Be sure to look also at wxStandardPaths if you only want to search files in
22 @see wxArrayString, wxStandardPaths, wxFileName
24 class wxPathList
: public wxArrayString
30 Constructs the object calling the Add() function.
32 wxPathList(const wxArrayString
& arr
);
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.
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).
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).
45 bool Add(const wxString
& path
);
48 Adds all elements of the given array as paths.
50 void Add(const wxArrayString
& arr
);
53 Finds the value of the given environment variable, and adds all paths
56 Useful for finding files in the @c PATH variable, for example.
58 void AddEnvList(const wxString
& env_variable
);
61 Given a full filename (with path), calls Add() with the path of the file.
63 bool EnsureFileAccessible(const wxString
& filename
);
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.
70 wxString
FindAbsoluteValidPath(const wxString
& file
) const;
73 Searches the given file in all paths stored in this class.
75 The first path which concatenated to the given string points to an existing
76 file (see wxFileExists()) is returned.
78 If the file wasn't found in any of the stored paths, an empty string is returned.
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
85 The returned path may be relative to the current working directory.
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
92 wxString
FindValidPath(const wxString
& file
) const;
97 // ============================================================================
98 // Global functions/macros
99 // ============================================================================
101 /** @addtogroup group_funcmacro_file */
105 A special return value of many wxWidgets classes to indicate that
106 an invalid offset was given.
108 const int wxInvalidOffset
= -1;
111 The type used to store and provide byte offsets or byte sizes for files or streams.
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.
117 typedef off_t wxFileOffset
;
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.
128 #define wxCHANGE_UMASK(mask)
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
138 @note The generic Unix implementation depends on the system having the
139 @c statfs() or @c statvfs() function.
141 @return @true on success, @false if an error occurred (for example, the
142 directory doesn’t exist).
146 bool wxGetDiskSpace(const wxString
& path
,
147 wxLongLong total
= NULL
,
148 wxLongLong free
= NULL
);
151 Returns the Windows directory under Windows; other platforms return an
156 wxString
wxGetOSDirectory();
159 Parses the @a wildCard, returning the number of filters. Returns 0 if none
160 or if there's a problem.
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:
167 "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
172 int wxParseCommonDialogsFilter(const wxString
& wildCard
,
173 wxArrayString
& descriptions
,
174 wxArrayString
& filters
);
177 Converts a DOS to a Unix filename by replacing backslashes with forward
181 Construct a wxFileName with wxPATH_DOS and then use
182 wxFileName::GetFullPath(wxPATH_UNIX) instead.
186 void wxDos2UnixFilename(wxChar
* s
);
189 Converts a Unix to a DOS filename by replacing forward slashes with
193 Construct a wxFileName with wxPATH_UNIX and then use
194 wxFileName::GetFullPath(wxPATH_DOS) instead.
198 void wxUnix2DosFilename(wxChar
* s
);
201 Returns @true if @a dirname exists and is a directory.
205 bool wxDirExists(const wxString
& dirname
);
209 This function is obsolete, please use wxFileName::SplitPath() instead.
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.
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).
220 On entry, @a fullname should be non-@NULL (it may be empty though).
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).
230 void wxSplitPath(const wxString
& fullname
,
236 Returns time of last modification of given file.
238 The function returns <tt>(time_t)-1</tt> if an error occurred (e.g. file
243 time_t wxFileModificationTime(const wxString
& filename
);
246 Renames @a file1 to @e file2, returning @true if successful.
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
254 bool wxRenameFile(const wxString
& file1
,
255 const wxString
& file2
,
256 bool overwrite
= true);
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.
263 This function supports resources forks under Mac OS.
267 bool wxCopyFile(const wxString
& file1
,
268 const wxString
& file2
,
269 bool overwrite
= true);
272 Returns @true if the file exists and is a plain file.
276 bool wxFileExists(const wxString
& filename
);
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
287 bool wxMatchWild(const wxString
& pattern
,
288 const wxString
& text
,
292 @deprecated This function is deprecated, use wxGetCwd() instead.
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
298 @a sz is the size of the buffer if supplied.
302 wxString
wxGetWorkingDirectory(char* buf
= NULL
, int sz
= 1000);
305 Returns the directory part of the filename.
309 wxString
wxPathOnly(const wxString
& path
);
312 Returns @true if the pattern contains wildcards.
318 bool wxIsWild(const wxString
& pattern
);
321 Returns @true if the argument is an absolute filename, i.e. with a slash
322 or drive name at the beginning.
326 bool wxIsAbsolutePath(const wxString
& filename
);
329 Returns a string containing the current (or working) directory.
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.
342 bool wxSetWorkingDirectory(const wxString
& dir
);
345 Concatenates @a file1 and @a file2 to @e file3, returning @true if
350 bool wxConcatFiles(const wxString
& file1
,
351 const wxString
& file2
,
352 const wxString
& file3
);
355 Removes @e file, returning @true if successful.
359 bool wxRemoveFile(const wxString
& file
);
362 File permission bit names.
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.
367 enum wxPosixPermissions
369 /// Standard POSIX names for these permission flags with "wx" prefix.
384 /// Longer but more readable synonyms for the constants above.
386 wxPOSIX_USER_READ
= wxS_IRUSR
,
387 wxPOSIX_USER_WRITE
= wxS_IWUSR
,
388 wxPOSIX_USER_EXECUTE
= wxS_IXUSR
,
390 wxPOSIX_GROUP_READ
= wxS_IRGRP
,
391 wxPOSIX_GROUP_WRITE
= wxS_IWGRP
,
392 wxPOSIX_GROUP_EXECUTE
= wxS_IXGRP
,
394 wxPOSIX_OTHERS_READ
= wxS_IROTH
,
395 wxPOSIX_OTHERS_WRITE
= wxS_IWOTH
,
396 wxPOSIX_OTHERS_EXECUTE
= wxS_IXOTH
,
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
),
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
)
415 Makes the directory @a dir, returning @true if successful.
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.
422 bool wxMkdir(const wxString
& dir
, int perm
= wxS_DIR_DEFAULT
);
425 Removes the directory @a dir, returning @true if successful. Does not work
428 The @a flags parameter is reserved for future use.
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.
437 bool wxRmdir(const wxString
& dir
, int flags
= 0);
440 Returns the next file that matches the path passed to wxFindFirstFile().
442 See wxFindFirstFile() for an example.
446 wxString
wxFindNextFile();
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
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.
458 @a spec may contain wildcards.
460 @a flags may be wxDIR for restricting the query to directories, wxFILE for
461 files or zero for either.
466 wxString f = wxFindFirstFile("/home/project/*.*");
470 f = wxFindNextFile();
476 wxString
wxFindFirstFile(const wxString
& spec
, int flags
= 0);
479 File kind enumerations returned from wxGetFileKind().
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
493 /** @addtogroup group_funcmacro_file */
496 Returns the type of an open file. Possible return values are enumerations
501 wxFileKind
wxGetFileKind(int fd
);
502 wxFileKind
wxGetFileKind(FILE* fp
);
505 /** @addtogroup group_funcmacro_file */
509 This function is obsolete, please use wxFileName::SplitPath() instead.
511 Returns the filename for a full path. The second form returns a pointer to
512 temporary storage that should not be deallocated.
516 wxString
wxFileNameFromPath(const wxString
& path
);
517 char* wxFileNameFromPath(char* path
);
520 /** @addtogroup group_funcmacro_file */
524 This function is obsolete, please use wxFileName::CreateTempFileName() instead.
528 char* wxGetTempFileName(const wxString
& prefix
, char* buf
= NULL
);
529 bool wxGetTempFileName(const wxString
& prefix
, wxString
& buf
);