interface/wx/metafile.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        metafile.h
   3 // Purpose:     interface of wxMetafileDC
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxMetafileDC
  10
  11     This is a type of device context that allows a metafile object to be
  12     created (Windows only), and has most of the characteristics of a normal
  13     @b wxDC.
  14     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
  17     (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 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 closing your disk-based
  27     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.
  39         If no filename is passed, the metafile is created in memory.
  40     */
  41     wxMetafileDC(const wxString& filename = wxEmptyString);
  42
  43     /**
  44         Destructor.
  45     */
  46     ~wxMetafileDC();
  47
  48     /**
  49         This must be called after the device context is finished with.
  50         A 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.
  65
  66     Presently, the only way of creating a metafile is to use a wxMetafileDC.
  67
  68     @onlyfor{wxmsw}
  69
  70     @library{wxcore}
  71     @category{gdi}
  72
  73     @see wxMetafileDC
  74 */
  75 class wxMetafile : public wxObject
  76 {
  77 public:
  78     /**
  79         Constructor.
  80
  81         If a filename is given, the Windows disk metafile is read in.
  82         Check whether this was performed successfully by using the IsOk() member.
  83     */
  84     wxMetafile(const wxString& filename = wxEmptyString);
  85
  86     /**
  87         Destructor.
  88
  89         See @ref overview_refcount_destruct for more info.
  90     */
  91     ~wxMetafile();
  92
  93     /**
  94         Returns @true if the metafile is valid.
  95     */
  96     bool IsOk();
  97
  98     /**
  99         Plays the metafile into the given device context, returning
 100         @true if successful.
 101     */
 102     bool Play(wxDC* dc);
 103
 104     /**
 105         Passes the metafile data to the clipboard. The metafile can no longer be
 106         used for anything, but the wxMetafile object must still be destroyed by
 107         the application.
 108
 109         Below is a example of metafile, metafile device context and clipboard use
 110         from the @c hello.cpp example. Note the way the metafile dimensions
 111         are passed to the clipboard, making use of the device context's ability
 112         to keep track of the maximum extent of drawing commands.
 113
 114         @code
 115         wxMetafileDC dc;
 116         if (dc.IsOk())
 117         {
 118             Draw(dc, false);
 119             wxMetafile *mf = dc.Close();
 120             if (mf)
 121             {
 122                 bool success = mf->SetClipboard((int)(dc.MaxX() + 10), (int)(dc.MaxY() + 10));
 123                 delete mf;
 124             }
 125         }
 126         @endcode
 127     */
 128     bool SetClipboard(int width = 0, int height = 0);
 129 };
 130
 131
 132
 133 // ============================================================================
 134 // Global functions/macros
 135 // ============================================================================
 136
 137 /** @addtogroup group_funcmacro_gdi */
 138 //@{
 139
 140 /**
 141     Given a filename for an existing, valid metafile (as constructed using
 142     wxMetafileDC) makes it into a placeable metafile by prepending a header
 143     containing the given bounding box. The bounding box may be obtained from a
 144     device context after drawing into it, using the functions wxDC::MinX(),
 145     wxDC::MinY(), wxDC::MaxX() and wxDC::MaxY().
 146
 147     In addition to adding the placeable metafile header, this function adds the
 148     equivalent of the following code to the start of the metafile data:
 149
 150     @code
 151     SetMapMode(dc, MM_ANISOTROPIC);
 152     SetWindowOrg(dc, minX, minY);
 153     SetWindowExt(dc, maxX - minX, maxY - minY);
 154     @endcode
 155
 156     This simulates the wxMM_TEXT mapping mode, which wxWidgets assumes.
 157
 158     Placeable metafiles may be imported by many Windows applications, and can
 159     be used in RTF (Rich Text Format) files.
 160
 161     @a scale allows the specification of scale for the metafile.
 162
 163     This function is only available under Windows.
 164
 165     @header{wx/metafile.h}
 166 */
 167 bool wxMakeMetafilePlaceable(const wxString& filename,
 168                               int minX, int minY,
 169                               int maxX, int maxY,
 170                               float scale = 1.0);
 171
 172 //@}
 173