Clarify that Raise() is only a request to raise the window.

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

diff --git a/interface/wx/metafile.h b/interface/wx/metafile.h
index f994f22cecfb055d25a0737a66fa1d46c6828b88..cf541c567e69e43803a136186fcf3cfdf879dba3 100644 (file)
--- a/interface/wx/metafile.h
+++ b/interface/wx/metafile.h
@@ -8,24 +8,24 @@
 
 /**
     @class wxMetafileDC
-    @wxheader{metafile.h}
 
     This is a type of device context that allows a metafile object to be
     created (Windows only), and has most of the characteristics of a normal
-    @b wxDC. The wxMetafileDC::Close member must be called after drawing into the
+    @b wxDC.
+    The wxMetafileDC::Close member must be called after drawing into the
     device context, to return a metafile. The only purpose for this at
-    present is to allow the metafile to be copied to the clipboard (see wxMetafile).
+    present is to allow the metafile to be copied to the clipboard
+    (see wxMetafile).
 
     Adding metafile capability to an application should be easy if you
     already write to a wxDC; simply pass the wxMetafileDC to your drawing
     function instead. You may wish to conditionally compile this code so it
-    is not compiled under X (although no harm will result if you leave it
-    in).
+    is not compiled under X (although no harm will result if you leave it in).
 
     Note that a metafile saved to disk is in standard Windows metafile format,
     and cannot be imported into most applications. To make it importable,
-    call the function ::wxMakeMetafilePlaceable after
-    closing your disk-based metafile device context.
+    call the function ::wxMakeMetafilePlaceable after closing your disk-based
+    metafile device context.
 
     @library{wxcore}
     @category{dc}
@@ -36,10 +36,10 @@ class wxMetafileDC : public wxDC
 {
 public:
     /**
-        Constructor. If no filename is passed, the metafile is created
-        in memory.
+        Constructor.
+        If no filename is passed, the metafile is created in memory.
     */
-    wxMetafileDC(const wxString& filename = "");
+    wxMetafileDC(const wxString& filename = wxEmptyString);
 
     /**
         Destructor.
@@ -47,8 +47,8 @@ public:
     ~wxMetafileDC();
 
     /**
-        This must be called after the device context is finished with. A
-        metafile is returned, and ownership of it passes to the calling
+        This must be called after the device context is finished with.
+        A metafile is returned, and ownership of it passes to the calling
         application (so it should be destroyed explicitly).
     */
     wxMetafile* Close();
@@ -58,16 +58,18 @@ public:
 
 /**
     @class wxMetafile
-    @wxheader{metafile.h}
 
     A @b wxMetafile represents the MS Windows metafile object, so metafile
     operations have no effect in X. In wxWidgets, only sufficient functionality
     has been provided for copying a graphic to the clipboard; this may be extended
-    in a future version. Presently, the only way of creating a metafile
-    is to use a wxMetafileDC.
+    in a future version.
+
+    Presently, the only way of creating a metafile is to use a wxMetafileDC.
+
+    @onlyfor{wxmsw}
 
     @library{wxcore}
-    @category{FIXME}
+    @category{gdi}
 
     @see wxMetafileDC
 */
@@ -75,23 +77,24 @@ class wxMetafile : public wxObject
 {
 public:
     /**
-        Constructor. If a filename is given, the Windows disk metafile is
-        read in. Check whether this was performed successfully by
-        using the @ref isok() wxMetafile:IsOk member.
+        Constructor.
+
+        If a filename is given, the Windows disk metafile is read in.
+        Check whether this was performed successfully by using the IsOk() member.
     */
-    wxMetafile(const wxString& filename = "");
+    wxMetafile(const wxString& filename = wxEmptyString);
 
     /**
         Destructor.
-        See @ref overview_refcountdestruct "reference-counted object destruction" for
-        more info.
+
+        See @ref overview_refcount_destruct for more info.
     */
     ~wxMetafile();
 
     /**
         Returns @true if the metafile is valid.
     */
-    bool Ok();
+    bool IsOk();
 
     /**
         Plays the metafile into the given device context, returning
@@ -103,10 +106,25 @@ public:
         Passes the metafile data to the clipboard. The metafile can no longer be
         used for anything, but the wxMetafile object must still be destroyed by
         the application.
+
         Below is a example of metafile, metafile device context and clipboard use
         from the @c hello.cpp example. Note the way the metafile dimensions
         are passed to the clipboard, making use of the device context's ability
         to keep track of the maximum extent of drawing commands.
+
+        @code
+        wxMetafileDC dc;
+        if (dc.IsOk())
+        {
+            Draw(dc, false);
+            wxMetafile *mf = dc.Close();
+            if (mf)
+            {
+                bool success = mf->SetClipboard((int)(dc.MaxX() + 10), (int)(dc.MaxY() + 10));
+                delete mf;
+            }
+        }
+        @endcode
     */
     bool SetClipboard(int width = 0, int height = 0);
 };
@@ -117,7 +135,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/** @ingroup group_funcmacro_gdi */
+/** @addtogroup group_funcmacro_gdi */
 //@{
 
 /**