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