revised m*h headers

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56227 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/metafile.h

@@ -11,20 +11,21 @@
 
     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}
@@ -35,8 +36,8 @@ 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 = "");
 
@@ -46,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();
@@ -61,11 +62,14 @@ public:
     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,misc}
 
     @see wxMetafileDC
 */
@@ -73,16 +77,17 @@ 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 = "");
 
     /**
         Destructor.
-        See @ref overview_refcountdestruct "reference-counted object destruction" for
-        more info.
+
+        See @ref overview_refcount_destruct for more info.
     */
     ~wxMetafile();
 
@@ -101,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.Ok())
+        {
+            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);
 };