X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..592584e4e9c3c01a05fda770dcd1f88a8a8d69f1:/interface/filefn.h diff --git a/interface/filefn.h b/interface/filefn.h index 9e239fefdc..ee4cd58bca 100644 --- a/interface/filefn.h +++ b/interface/filefn.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: filefn.h -// Purpose: documentation for wxPathList class +// Purpose: interface of wxPathList and file functions // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -11,18 +11,16 @@ @wxheader{filefn.h} The path list is a convenient way of storing a number of directories, and - when presented with a filename without a directory, searching for an existing - file - in those directories. + when presented with a filename without a directory, searching for an + existing file in those directories. - Be sure to look also at wxStandardPaths if you only - want to search files in some standard paths. + Be sure to look also at wxStandardPaths if you only want to search files in + some standard paths. @library{wxbase} @category{file} - @seealso - wxArrayString, wxStandardPaths, wxFileName + @see wxArrayString, wxStandardPaths, wxFileName */ class wxPathList : public wxArrayString { @@ -73,12 +71,12 @@ public: to the value returned wxPathList::FindValidPath) or an empty string. */ - wxString FindAbsoluteValidPath(const wxString& file); + wxString FindAbsoluteValidPath(const wxString& file) const; /** Searches the given file in all paths stored in this class. The first path which concatenated to the given string points to an existing - file (see @ref wxFile::exists wxFileExists) is returned. + file (see wxFileExists()) is returned. If the file wasn't found in any of the stored paths, an empty string is returned. The given string must be a file name, eventually with a path prefix (if the path @@ -89,262 +87,372 @@ public: Note in fact that wxPathList can be used to store both relative and absolute paths so that if you Added() relative paths, then the current working directory - (see wxGetCwd and wxSetWorkingDirectory) + (see wxGetCwd() and wxSetWorkingDirectory()) may affect the value returned by this function! */ - wxString FindValidPath(const wxString& file); + wxString FindValidPath(const wxString& file) const; }; + // ============================================================================ // Global functions/macros // ============================================================================ +/** @ingroup group_funcmacro_file */ +//@{ + +/** + Under Unix this macro changes the current process umask to the given value, + unless it is equal to -1 in which case nothing is done, and restores it to + the original value on scope exit. It works by declaring a variable which + sets umask to @a mask in its constructor and restores it in its destructor. + Under other platforms this macro expands to nothing. + + @header{wx/filefn.h} +*/ +#define wxCHANGE_UMASK(int mask) + /** This function returns the total number of bytes and number of free bytes on - the disk containing the directory @a path (it should exist). Both - @a total and @a free parameters may be @NULL if the corresponding - information is not needed. + the disk containing the directory @a path (it should exist). Both @a total + and @a free parameters may be @NULL if the corresponding information is not + needed. + + @wxsince{2.3.2} + + @note The generic Unix implementation depends on the system having the + @c statfs() or @c statvfs() function. + + @returns @true on success, @false if an error occurred (for example, the + directory doesn’t exist). + + @header{wx/filefn.h} */ bool wxGetDiskSpace(const wxString& path, wxLongLong total = NULL, wxLongLong free = NULL); /** - Returns the Windows directory under Windows; on other platforms returns the + Returns the Windows directory under Windows; other platforms return an empty string. + + @header{wx/filefn.h} */ wxString wxGetOSDirectory(); /** - Parses the @e wildCard, returning the number of filters. - Returns 0 if none or if there's a problem. - The arrays will contain an equal number of items found before the error. - On platforms where native dialogs handle only one filter per entry, - entries in arrays are automatically adjusted. - @a wildCard is in the form: + Parses the @a wildCard, returning the number of filters. Returns 0 if none + or if there's a problem. + + The arrays will contain an equal number of items found before the error. On + platforms where native dialogs handle only one filter per entry, entries in + arrays are automatically adjusted. @a wildCard is in the form: @code "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" @endcode + + @header{wx/filefn.h} */ int wxParseCommonDialogsFilter(const wxString& wildCard, wxArrayString& descriptions, wxArrayString& filters); /** - This function is deprecated, use wxFileName instead. - Converts a Unix to a DOS filename by replacing forward - slashes with backslashes. + Converts a DOS to a Unix filename by replacing backslashes with forward + slashes. + + @header{wx/filefn.h} +*/ +void wxDos2UnixFilename(wxChar* s); + +/** + @warning This function is deprecated, use wxFileName instead. + + Converts a Unix to a DOS filename by replacing forward slashes with + backslashes. + + @header{wx/filefn.h} */ void wxUnix2DosFilename(wxChar* s); /** Returns @true if @a dirname exists and is a directory. + + @header{wx/filefn.h} */ bool wxDirExists(const wxString& dirname); /** - @b NB: This function is obsolete, please use - wxFileName::SplitPath instead. + @warning This function is obsolete, please use wxFileName::SplitPath() + instead. + This function splits a full file name into components: the path (including - possible disk/drive - specification under Windows), the base name and the extension. Any of the - output parameters - (@e path, @a name or @e ext) may be @NULL if you are not interested in the value - of - a particular component. + possible disk/drive specification under Windows), the base name, and the + extension. Any of the output parameters (@a path, @a name or @a ext) may be + @NULL if you are not interested in the value of a particular component. + wxSplitPath() will correctly handle filenames with both DOS and Unix path - separators under - Windows, however it will not consider backslashes as path separators under Unix - (where backslash - is a valid character in a filename). + separators under Windows, however it will not consider backslashes as path + separators under Unix (where backslash is a valid character in a filename). + On entry, @a fullname should be non-@NULL (it may be empty though). - On return, @a path contains the file path (without the trailing separator), @e - name - contains the file name and @a ext contains the file extension without leading - dot. All - three of them may be empty if the corresponding component is. The old contents - of the - strings pointed to by these parameters will be overwritten in any case (if the - pointers - are not @NULL). -*/ -void wxSplitPath(const wxString& fullname, wxString* path, - wxString* name, - wxString* ext); -/** - Under Unix this macro changes the current process umask to the given value, - unless it is equal to -1 in which case nothing is done, and restores it to - the original value on scope exit. It works by declaring a variable which sets - umask to @a mask in its constructor and restores it in its destructor. - Under other platforms this macro expands to nothing. + On return, @a path contains the file path (without the trailing separator), + @a name contains the file name and @c ext contains the file extension + without leading dot. All three of them may be empty if the corresponding + component is. The old contents of the strings pointed to by these + parameters will be overwritten in any case (if the pointers are not @NULL). + + @header{wx/filefn.h} */ -#define wxCHANGE_UMASK(int mask) /* implementation is private */ +void wxSplitPath(const wxString& fullname, + wxString* path, + wxString* name, + wxString* ext); /** Returns time of last modification of given file. - The function returns @c (time_t)-1 if an error occurred (e.g. file not - found). -*/ -time_t wxFileModificationTime(const wxString& filename); -//@{ -/** - @b NB: This function is obsolete, please use - wxFileName::SplitPath instead. - Returns the filename for a full path. The second form returns a pointer to - temporary storage that should not be deallocated. + The function returns (time_t)-1 if an error occurred (e.g. file + not found). + + @header{wx/filefn.h} */ -wxString wxFileNameFromPath(const wxString& path); -char* wxFileNameFromPath(char* path); -//@} +time_t wxFileModificationTime(const wxString& filename); /** Renames @a file1 to @e file2, returning @true if successful. + If @a overwrite parameter is @true (default), the destination file is - overwritten if it exists, but if @a overwrite is @false, the functions fails - in this case. + overwritten if it exists, but if @a overwrite is @false, the functions + fails in this case. + + @header{wx/filefn.h} */ -bool wxRenameFile(const wxString& file1, const wxString& file2, - bool overwrite = true); +bool wxRenameFile(const wxString& file1, + const wxString& file2, + bool overwrite = true); /** - Copies @a file1 to @e file2, returning @true if successful. If - @a overwrite parameter is @true (default), the destination file is overwritten - if it exists, but if @a overwrite is @false, the functions fails in this - case. + Copies @a file1 to @e file2, returning @true if successful. If @a overwrite + parameter is @true (default), the destination file is overwritten if it + exists, but if @a overwrite is @false, the functions fails in this case. + This function supports resources forks under Mac OS. + + @header{wx/filefn.h} */ -bool wxCopyFile(const wxString& file1, const wxString& file2, - bool overwrite = true); +bool wxCopyFile(const wxString& file1, + const wxString& file2, + bool overwrite = true); /** Returns @true if the file exists and is a plain file. + + @header{wx/filefn.h} */ bool wxFileExists(const wxString& filename); /** - Returns @true if the @a pattern matches the @e text; if @a dot_special is @true, - filenames beginning with a dot are not matched - with wildcard characters. See wxIsWild. + Returns @true if the @a pattern matches the @e text; if @a dot_special is + @true, filenames beginning with a dot are not matched with wildcard + characters. + + @see wxIsWild() + + @header{wx/filefn.h} */ -bool wxMatchWild(const wxString& pattern, const wxString& text, - bool dot_special); +bool wxMatchWild(const wxString& pattern, + const wxString& text, + bool dot_special); /** - @b NB: This function is deprecated: use wxGetCwd instead. - Copies the current working directory into the buffer if supplied, or - copies the working directory into new storage (which you must delete - yourself) if the buffer is @NULL. + @warning This function is deprecated, use wxGetCwd() instead. + + Copies the current working directory into the buffer if supplied, or copies + the working directory into new storage (which you must delete yourself) if + the buffer is @NULL. + @a sz is the size of the buffer if supplied. + + @header{wx/filefn.h} */ wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000); /** Returns the directory part of the filename. + + @header{wx/filefn.h} */ wxString wxPathOnly(const wxString& path); /** - Returns @true if the pattern contains wildcards. See wxMatchWild. + Returns @true if the pattern contains wildcards. + + @see wxMatchWild() + + @header{wx/filefn.h} */ bool wxIsWild(const wxString& pattern); +/** + Returns @true if the argument is an absolute filename, i.e. with a slash + or drive name at the beginning. + + @header{wx/filefn.h} +*/ +bool wxIsAbsolutePath(const wxString& filename); + /** Returns a string containing the current (or working) directory. + + @header{wx/filefn.h} */ wxString wxGetCwd(); /** - Converts a DOS to a Unix filename by replacing backslashes with forward - slashes. + Sets the current working directory, returning @true if the operation + succeeded. Under MS Windows, the current drive is also changed if @a dir + contains a drive specification. + + @header{wx/filefn.h} */ -void wxDos2UnixFilename(wxChar* s); +bool wxSetWorkingDirectory(const wxString& dir); /** - Concatenates @a file1 and @a file2 to @e file3, returning - @true if successful. + Concatenates @a file1 and @a file2 to @e file3, returning @true if + successful. + + @header{wx/filefn.h} */ -bool wxConcatFiles(const wxString& file1, const wxString& file2, - const wxString& file3); +bool wxConcatFiles(const wxString& file1, + const wxString& file2, + const wxString& file3); /** Removes @e file, returning @true if successful. + + @header{wx/filefn.h} */ bool wxRemoveFile(const wxString& file); /** - Sets the current working directory, returning @true if the operation succeeded. - Under MS Windows, the current drive is also changed if @a dir contains a drive - specification. -*/ -bool wxSetWorkingDirectory(const wxString& dir); + Makes the directory @a dir, returning @true if successful. -/** - Makes the directory @e dir, returning @true if successful. @a perm is the access mask for the directory for the systems on which it is supported (Unix) and doesn't have any effect on the other ones. + + @header{wx/filefn.h} */ bool wxMkdir(const wxString& dir, int perm = 0777); /** - Returns @true if the argument is an absolute filename, i.e. with a slash - or drive name at the beginning. + Removes the directory @a dir, returning @true if successful. Does not work + under VMS. + + The @a flags parameter is reserved for future use. + + @note There is also a wxRmDir() function which simply wraps the standard + POSIX @c rmdir() function and so return an integer error code instead + of a boolean value (but otherwise is currently identical to + wxRmdir()), don't confuse these two functions. + + @header{wx/filefn.h} */ -bool wxIsAbsolutePath(const wxString& filename); +bool wxRmdir(const wxString& dir, int flags = 0); /** - Returns the next file that matches the path passed to wxFindFirstFile. - See wxFindFirstFile for an example. + Returns the next file that matches the path passed to wxFindFirstFile(). + + See wxFindFirstFile() for an example. + + @header{wx/filefn.h} */ wxString wxFindNextFile(); /** - This function does directory searching; returns the first file - that matches the path @e spec, or the empty string. Use wxFindNextFile to - get the next matching file. Neither will report the current directory "." or the - parent directory "..". + This function does directory searching; returns the first file that matches + the path @a spec, or the empty string. Use wxFindNextFile() to get the next + matching file. Neither will report the current directory "." or the parent + directory "..". + + @warning As of 2.5.2, these functions are not thread-safe! (they use static + variables). You probably want to use wxDir::GetFirst() or + wxDirTraverser instead. + + @a spec may contain wildcards. + + @a flags may be wxDIR for restricting the query to directories, wxFILE for + files or zero for either. + + For example: + + @code + wxString f = wxFindFirstFile("/home/project/*.*"); + while ( !f.empty() ) + { + ... + f = wxFindNextFile(); + } + @endcode + + @header{wx/filefn.h} */ wxString wxFindFirstFile(const wxString& spec, int flags = 0); +/** + File kind enumerations returned from wxGetFileKind(). + + @header{wx/filefn.h} +*/ +enum wxFileKind +{ + wxFILE_KIND_UNKNOWN, ///< Unknown file kind, or unable to determine + wxFILE_KIND_DISK, ///< A file supporting seeking to arbitrary offsets + wxFILE_KIND_TERMINAL, ///< A tty + wxFILE_KIND_PIPE ///< A pipe +}; + +//@} + +/** @ingroup group_funcmacro_file */ //@{ /** - Returns the type of an open file. Possible return values are: + Returns the type of an open file. Possible return values are enumerations + of ::wxFileKind. - @code - enum wxFileKind - { - wxFILE_KIND_UNKNOWN, - wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets - wxFILE_KIND_TERMINAL, // a tty - wxFILE_KIND_PIPE // a pipe - }; - @endcode + @header{wx/filefn.h} */ wxFileKind wxGetFileKind(int fd); wxFileKind wxGetFileKind(FILE* fp); //@} +/** @ingroup group_funcmacro_file */ //@{ /** - @b NB: These functions are obsolete, please use - wxFileName::CreateTempFileName - instead. + @warning This function is obsolete, please use wxFileName::SplitPath() + instead. + + Returns the filename for a full path. The second form returns a pointer to + temporary storage that should not be deallocated. + + @header{wx/filefn.h} */ -char* wxGetTempFileName(const wxString& prefix, char* buf = NULL); -bool wxGetTempFileName(const wxString& prefix, wxString& buf); +wxString wxFileNameFromPath(const wxString& path); +char* wxFileNameFromPath(char* path); //@} +/** @ingroup group_funcmacro_file */ +//@{ /** - Removes the directory @e dir, returning @true if successful. Does not work under - VMS. - The @a flags parameter is reserved for future use. - Please notice that there is also a wxRmDir() function which simply wraps the - standard POSIX rmdir() function and so return an integer error code instead of - a boolean value (but otherwise is currently identical to wxRmdir), don't - confuse these two functions. + @warning This function is obsolete, please use + wxFileName::CreateTempFileName() instead. + + @header{wx/filefn.h} */ -bool wxRmdir(const wxString& dir, int flags = 0); +char* wxGetTempFileName(const wxString& prefix, char* buf = NULL); +bool wxGetTempFileName(const wxString& prefix, wxString& buf); +//@}