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