Fix wxGCDC::Clear() for Cairo, and possibly MSW.

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

diff --git a/interface/wx/filename.h b/interface/wx/filename.h
index 7bbd0cd527c181b594b43b9ce982ddf04788f407..0c8171b0337371973834b641867d0c47486da35b 100644 (file)
--- a/interface/wx/filename.h
+++ b/interface/wx/filename.h
@@ -421,42 +421,59 @@ public:
     */
     void ClearExt();
 
-    //@{
+
     /**
         Returns a temporary file name starting with the given @e prefix.
-        If the @a prefix is an absolute path, the temporary file is created in this
-        directory, otherwise it is created in the default system directory for the
-        temporary files or in the current directory.
+        If @a prefix is an absolute path and ends in a separator, the
+        temporary file is created in this directory; if it is an absolute
+        filepath or there is no separator, the temporary file is created in its
+        path, with the 'name' segment prepended to the temporary filename;
+        otherwise it is created in the default system directory for temporary
+        files or in the current directory.
 
         If the function succeeds, the temporary file is actually created.
-        If @a fileTemp is not @NULL, this file will be opened using the name of
-        the temporary file. When possible, this is done in an atomic way ensuring that
-        no race condition occurs between the temporary file name generation and opening
-        it which could often lead to security compromise on the multiuser systems.
-        If @a fileTemp is @NULL, the file is only created, but not opened.
+        If @a fileTemp is not @NULL, this wxFile will be opened using the name of
+        the temporary file. Where possible this is done in an atomic way to ensure that
+        no race condition occurs between creating the temporary file name and opening
+        it, which might lead to a security compromise on multiuser systems.
+        If @a fileTemp is @NULL, the file is created but not opened.
         Under Unix, the temporary file will have read and write permissions for the
-        owner only to minimize the security problems.
+        owner only, to minimize security problems.
 
         @param prefix
-            Prefix to use for the temporary file name construction
+            Location to use for the temporary file name construction. If @a prefix
+            is a directory it must have a terminal separator
         @param fileTemp
-            The file to open or @NULL to just get the name
+            The file to open, or @NULL just to get the name
 
-        @return The full temporary file name or an empty string on error.
+        @return The full temporary filepath, or an empty string on error.
     */
     static wxString CreateTempFileName(const wxString& prefix,
                                        wxFile* fileTemp = NULL);
+
+    /**
+        This is the same as CreateTempFileName(const wxString &prefix, wxFile *fileTemp)
+        but takes a wxFFile parameter instead of wxFile.
+    */
     static wxString CreateTempFileName(const wxString& prefix,
                                        wxFFile* fileTemp = NULL);
-    //@}
+
 
     /**
         Returns @true if the directory with this name exists.
+
+        Notice that this function tests the directory part of this object,
+        i.e. the string returned by GetPath(), and not the full path returned
+        by GetFullPath().
+
+        @see FileExists(), Exists()
     */
     bool DirExists() const;
 
     /**
         Returns @true if the directory with name @a dir exists.
+
+        @see FileExists(), Exists()
     */
     static bool DirExists(const wxString& dir);
 
@@ -467,17 +484,40 @@ public:
     static wxFileName DirName(const wxString& dir,
                               wxPathFormat format = wxPATH_NATIVE);
 
+    /**
+        Calls the static overload of this function with the full path of this
+        object.
+
+        @since 2.9.4
+     */
+    bool Exists() const;
+
+    /**
+        Returns @true if either a file or a directory or something else with
+        this name exists in the file system.
+
+        This method is equivalent to @code FileExists() || DirExists() @endcode
+        under most systems but under Unix it also returns true if the file
+        identifies a special file system object such as a device, a socket or a
+        FIFO.
+
+        @since 2.9.4
+
+        @see FileExists(), DirExists()
+     */
+    static bool Exists(const wxString& path);
+
     /**
         Returns @true if the file with this name exists.
 
-        @see DirExists()
+        @see DirExists(), Exists()
     */
     bool FileExists() const;
 
     /**
         Returns @true if the file with name @a file exists.
 
-        @see DirExists()
+        @see DirExists(), Exists()
     */
     static bool FileExists(const wxString& file);
 
@@ -878,6 +918,8 @@ public:
 
     /**
         On Mac OS, gets the common type and creator for the given extension.
+
+        @onlyfor{wxosx}
     */
     static bool MacFindDefaultTypeAndCreator(const wxString& ext,
                                             wxUint32* type,
@@ -886,6 +928,8 @@ public:
     /**
         On Mac OS, registers application defined extensions and their default type
         and creator.
+
+        @onlyfor{wxosx}
     */
     static void MacRegisterDefaultTypeAndCreator(const wxString& ext,
                                                 wxUint32 type,
@@ -894,6 +938,8 @@ public:
     /**
         On Mac OS, looks up the appropriate type and creator from the registration
         and then sets it.
+
+        @onlyfor{wxosx}
     */
     bool MacSetDefaultTypeAndCreator();
 
@@ -1134,10 +1180,14 @@ public:
     void SetName(const wxString& name);
 
     /**
-        Sets the full path.
+        Sets the path.
+
+        The @a path argument includes both the path and the volume, if
+        supported by @a format.
 
-        The @a path argument includes both the path (and the volume, if
-        supported by @a format) and the name and extension.
+        Calling this function doesn't affect the name and extension components,
+        to change them as well you can use Assign() or just an assignment
+        operator.
 
         @see GetPath()
      */