Add documentation of wxFileSelectorEx() and wx{Load,Save}FileSelector().

[wxWidgets.git] / interface / wx / filefn.h

diff --git a/interface/wx/filefn.h b/interface/wx/filefn.h
index 1080f8f540b15fd421cf23b4fbbde362cc65cc0f..f2c9551b4f597e2ab09220079f1cfaa150cfec28 100644 (file)
--- a/interface/wx/filefn.h
+++ b/interface/wx/filefn.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxPathList and file functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -24,6 +24,9 @@
 class wxPathList : public wxArrayString
 {
 public:
+    /**
+        Standard constructor.
+    */
     wxPathList();
 
     /**
@@ -245,9 +248,10 @@ 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.
+    If @a file2 is a directory, @a file1 is moved into it (@a overwrite is
+    ignored in this case). Otherwise, if @a file2 is an existing file, it is
+    overwritten if @a overwrite is @true (default) and the function fails if @a
+    overwrite is @false.
 
     @header{wx/filefn.h}
 */
@@ -358,6 +362,59 @@ bool wxConcatFiles(const wxString& file1,
 */
 bool wxRemoveFile(const wxString& file);
 
+/**
+    File permission bit names.
+
+    We define these constants in wxWidgets because S_IREAD &c are not standard.
+    However, we do assume that the values correspond to the Unix umask bits.
+*/
+enum wxPosixPermissions
+{
+    /// Standard POSIX names for these permission flags with "wx" prefix.
+    //@{
+    wxS_IRUSR = 00400,
+    wxS_IWUSR = 00200,
+    wxS_IXUSR = 00100,
+
+    wxS_IRGRP = 00040,
+    wxS_IWGRP = 00020,
+    wxS_IXGRP = 00010,
+
+    wxS_IROTH = 00004,
+    wxS_IWOTH = 00002,
+    wxS_IXOTH = 00001,
+    //@}
+
+    /// Longer but more readable synonyms for the constants above.
+    //@{
+    wxPOSIX_USER_READ = wxS_IRUSR,
+    wxPOSIX_USER_WRITE = wxS_IWUSR,
+    wxPOSIX_USER_EXECUTE = wxS_IXUSR,
+
+    wxPOSIX_GROUP_READ = wxS_IRGRP,
+    wxPOSIX_GROUP_WRITE = wxS_IWGRP,
+    wxPOSIX_GROUP_EXECUTE = wxS_IXGRP,
+
+    wxPOSIX_OTHERS_READ = wxS_IROTH,
+    wxPOSIX_OTHERS_WRITE = wxS_IWOTH,
+    wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH,
+    //@}
+
+    /// Default mode for the new files: allow reading/writing them to everybody but
+    /// the effective file mode will be set after ANDing this value with umask and
+    /// so won't include wxS_IW{GRP,OTH} for the default 022 umask value
+    wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \
+                   wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \
+                   wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE),
+
+    /// Default mode for the new directories (see wxFileName::Mkdir): allow
+    /// reading/writing/executing them to everybody, but just like wxS_DEFAULT
+    /// the effective directory mode will be set after ANDing this value with umask
+    wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \
+                       wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \
+                       wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE)
+};
+
 /**
     Makes the directory @a dir, returning @true if successful.
 
@@ -366,7 +423,7 @@ bool wxRemoveFile(const wxString& file);
 
     @header{wx/filefn.h}
 */
-bool wxMkdir(const wxString& dir, int perm = 0777);
+bool wxMkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT);
 
 /**
     Removes the directory @a dir, returning @true if successful. Does not work
@@ -422,9 +479,25 @@ wxString wxFindNextFile();
 */
 wxString wxFindFirstFile(const wxString& spec, int flags = 0);
 
+/**
+    Parameter indicating how file offset should be interpreted.
+
+    This is used by wxFFile::Seek() and wxFile::Seek().
+
+    @header{wx/filefn.h}
+*/
+enum wxSeekMode
+{
+    wxFromStart,        ///< Seek from the file beginning.
+    wxFromCurrent,      ///< Seek from the current position.
+    wxFromEnd           ///< Seek from end of the file.
+};
+
 /**
     File kind enumerations returned from wxGetFileKind().
 
+    Also used by wxFFile::GetKind() and wxFile::GetKind().
+
     @header{wx/filefn.h}
 */
 enum wxFileKind