interface/metafile.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        metafile.h
   3 // Purpose:     interface of wxMetafileDC
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMetafileDC
  11     @wxheader{metafile.h}
  12
  13     This is a type of device context that allows a metafile object to be
  14     created (Windows only), and has most of the characteristics of a normal
  15     @b wxDC. The wxMetafileDC::Close member must be called after drawing into the
  16     device context, to return a metafile. The only purpose for this at
  17     present is to allow the metafile to be copied to the clipboard (see wxMetafile).
  18
  19     Adding metafile capability to an application should be easy if you
  20     already write to a wxDC; simply pass the wxMetafileDC to your drawing
  21     function instead. You may wish to conditionally compile this code so it
  22     is not compiled under X (although no harm will result if you leave it
  23     in).
  24
  25     Note that a metafile saved to disk is in standard Windows metafile format,
  26     and cannot be imported into most applications. To make it importable,
  27     call the function ::wxMakeMetafilePlaceable after
  28     closing your disk-based metafile device context.
  29
  30     @library{wxcore}
  31     @category{dc}
  32
  33     @see wxMetafile, wxDC
  34 */
  35 class wxMetafileDC : public wxDC
  36 {
  37 public:
  38     /**
  39         Constructor. If no filename is passed, the metafile is created
  40         in memory.
  41     */
  42     wxMetafileDC(const wxString& filename = "");
  43
  44     /**
  45         Destructor.
  46     */
  47     ~wxMetafileDC();
  48
  49     /**
  50         This must be called after the device context is finished with. A
  51         metafile is returned, and ownership of it passes to the calling
  52         application (so it should be destroyed explicitly).
  53     */
  54     wxMetafile* Close();
  55 };
  56
  57
  58
  59 /**
  60     @class wxMetafile
  61     @wxheader{metafile.h}
  62
  63     A @b wxMetafile represents the MS Windows metafile object, so metafile
  64     operations have no effect in X. In wxWidgets, only sufficient functionality
  65     has been provided for copying a graphic to the clipboard; this may be extended
  66     in a future version. Presently, the only way of creating a metafile
  67     is to use a wxMetafileDC.
  68
  69     @library{wxcore}
  70     @category{FIXME}
  71
  72     @see wxMetafileDC
  73 */
  74 class wxMetafile : public wxObject
  75 {
  76 public:
  77     /**
  78         Constructor. If a filename is given, the Windows disk metafile is
  79         read in. Check whether this was performed successfully by
  80         using the @ref isok() wxMetafile:IsOk member.
  81     */
  82     wxMetafile(const wxString& filename = "");
  83
  84     /**
  85         Destructor.
  86         See @ref overview_refcountdestruct "reference-counted object destruction" for
  87         more info.
  88     */
  89     ~wxMetafile();
  90
  91     /**
  92         Returns @true if the metafile is valid.
  93     */
  94     bool Ok();
  95
  96     /**
  97         Plays the metafile into the given device context, returning
  98         @true if successful.
  99     */
 100     bool Play(wxDC* dc);
 101
 102     /**
 103         Passes the metafile data to the clipboard. The metafile can no longer be
 104         used for anything, but the wxMetafile object must still be destroyed by
 105         the application.
 106         Below is a example of metafile, metafile device context and clipboard use
 107         from the @c hello.cpp example. Note the way the metafile dimensions
 108         are passed to the clipboard, making use of the device context's ability
 109         to keep track of the maximum extent of drawing commands.
 110     */
 111     bool SetClipboard(int width = 0, int height = 0);
 112 };
 113
 114
 115
 116 // ============================================================================
 117 // Global functions/macros
 118 // ============================================================================
 119
 120 /** @addtogroup group_gdi */
 121 //@{
 122
 123 /**
 124     @header{wx/metafile.h}
 125
 126     Given a filename for an existing, valid metafile (as constructed using
 127     wxMetafileDC) makes it into a placeable metafile by prepending a header
 128     containing the given bounding box. The bounding box may be obtained from a
 129     device context after drawing into it, using the functions wxDC::MinX(),
 130     wxDC::MinY(), wxDC::MaxX() and wxDC::MaxY(). In addition to adding the
 131     placeable metafile header, this function adds the equivalent of the
 132     following code to the start of the metafile data:
 133
 134     @code
 135     SetMapMode(dc, MM_ANISOTROPIC);
 136     SetWindowOrg(dc, minX, minY);
 137     SetWindowExt(dc, maxX - minX, maxY - minY);
 138     @endcode
 139
 140     This simulates the wxMM_TEXT mapping mode, which wxWidgets assumes.
 141     Placeable metafiles may be imported by many Windows applications, and can
 142     be used in RTF (Rich Text Format) files. @a scale allows the specification
 143     of scale for the metafile. This function is only available under Windows.
 144 */
 145 bool wxMakeMetafilePlaceable(const wxString& filename, int minX,
 146                              int minY,
 147                              int maxX,
 148                              int maxY,
 149                              float scale = 1.0);
 150
 151 //@}
 152