vcl/README.GDIMetaFile

   1 GDIMetaFile class
   2 =================
   3
   4 The GDIMetaFile class reads, writes, manipulates and replays metafiles via the VCL module.
   5
   6 A typical use case is to initialize a new GDIMetaFile, open the actual stored metafile and
   7 read it in via GDIMetaFile::Read( aIStream ). This reads in the metafile into the GDIMetafile
   8 object - it can read in an old-style VCLMTF metafile (back in the days that Microsoft didn't
   9 document the metafile format this was used), as well as EMF+ files - and adds them to a list
  10 (vector) of MetaActions. You can also populate your own GDIMetaFile via AddAction(),
  11 RemoveAction(), ReplaceAction(), etc.
  12
  13 Once the GDIMetafile object is read to be used, you can "play" the metafile, pause it, wind
  14 forward or rewind the metafile. The metafile can be moved, scaled, rotated and clipped, as
  15 well have the colours adjusted or replaced, or even made monochrome.
  16
  17 The GDIMetafile can be used to get an OutputDevice's metafile via the Linker() and Record()
  18 functions.
  19
  20
  21 Using GDIMetafile
  22 -----------------
  23
  24 First, create a new GDIMetafile, this can be done via the default constructor. It can then
  25 be constructed manually, or you can use Record() on an OutputDevice to populate the
  26 GDIMetaFile, or of course you can read it from file with Read(). From here you can then
  27 elect to manipulate the metafile, or play it back to another GDIMetafile or to an
  28 OutputDevice via Play(). To store the file, use Write().
  29
  30 CONSTRUCTORS AND DESTRUCTORS
  31
  32 - GDIMetaFile
  33 - GDIMetaFile( cosnt GDIMetaFile& rMtf ) - copy constructor
  34 - ~GDIMetaFile
  35
  36
  37 OPERATORS
  38
  39 - operator =
  40 - operator ==
  41 - operator !=
  42
  43
  44 RECORDING AND PLAYBACK FUNCTIONS
  45
  46 - Play(GDIMetaFile&, size_t)               - play back metafile into another metafile up
  47                                              to position
  48 - Play(OutputDevice*, size_t)              - play back metafile into OutputDevice up to
  49                                              position
  50 - Play(OutputDevice*, Point, Size, size_t) - play back metafile into OutputDevice at a
  51                                              particular location on the OutputDevice, up
  52                                              to the position in the metafile
  53 - Pause                                    - pauses or continues the playback
  54 - IsPause
  55 - Stop                                     - stop playback fully
  56 - WindStart                                - windback to start of the metafile
  57 - windPrev                                 - windback one record
  58 - GetActionSize                            - get the number of records in the metafile
  59
  60
  61 METAFILE RECORD FUNCTIONS
  62
  63 - FirstAction                              - get the first metafile record
  64 - NextAction                               - get the next metafile record from the
  65                                              current position
  66 - GetAction(size_t)                        - get the metafile record at location in file
  67 - GetCurAction                             - get the current metafile record
  68 - AddAction(MetaAction*)                   - appends a metafile record
  69 - AddAction(MetaAction*, size_t)           - adds a metafile record to a particular
  70                                              location in the file
  71 - RemoveAction                             - removes record at file location
  72 - Clear                                    - first stops if recording, then removes all
  73                                              metafile records
  74 - push_back                                - pushes back, basically a thin wrapper to the
  75                                              metafile record list
  76
  77
  78 READ AND WRITING
  79
  80 - Read
  81 - Write
  82 - GetChecksum
  83 - GetSizeBytes
  84
  85
  86 DISPLACEMENT FUNCTIONS
  87
  88 - Move( long nX, long nX)
  89 - Move( long nX, long nX, long nDPIX, long nDPIY ) - Move method getting specifics how to
  90                                              handle MapMode( MapUnit::MapPixel )
  91
  92
  93 TRANSFORMATION FUNCTIONS
  94
  95 - Scale( double fScaleX, double fScaleY )
  96 - Scale( const Fraction& rScaleX, const Fraction& rScaleY )
  97 - Mirror
  98 - Rotate( long nAngle10 )
  99 - Clip( const Rectangle& )
 100
 101
 102 COLOR ADJUSTMENT FUNCTIONS
 103
 104 - Adjust                                    - change luminance, contrast, gamma and RGB via a
 105                                               percentage
 106 - Convert                                   - colour conversion
 107 - ReplaceColors
 108 - GetMonochromeMtf
 109
 110
 111 Related classes
 112 ---------------
 113
 114 MetaAction: a base class used by all records. It implements a command-like pattern, and also
 115 acts as a prototype for other actions.
 116
 117
 118 CONSTRUCTORS AND DESTRUCTORS
 119
 120 - MetaAction()                              - default constructor, sets mnRefCount to 1 and
 121                                               mnType, in this case MetaActionType::NONE
 122 - MetaAction(sal_uInt16 nType)              - virtual constructor, sets mnType to nType, and
 123                                               mnRefCount to 1
 124 - ~MetaAction
 125
 126
 127 COMMAND FUNCTION
 128
 129 - Execute(OutputDevice*)                    - execute the functionality of the record to the
 130                                               OutputDevice. Part of command pattern.
 131
 132
 133 FACTORY FUNCTION
 134
 135 - Clone()                                   - prototype clone function
 136
 137
 138 MANIPULATION FUNCTIONS
 139
 140 - Move(long nHorzMove, long nVerMove)
 141 - Scale(double fScaleX, double fScaleY)
 142
 143
 144 READ AND WRITE FUNCTIONS
 145
 146 - Read
 147 - Write
 148 - ReadMetaAction                            - a static function, only used to determine which
 149                                               MetaAction to call on to read the record, which
 150                                               means that this is the function that must be used.
 151
 152
 153 INTROSPECTIVE FUNCTIONS
 154
 155 - GetType
 156 - GetRefCount                               - reference counter
 157 - ResetRefCount                             - reset to 1
 158 - Duplicate                                 - increment refcounter
 159 - Delete                                    - delete if all instances no longer being referenced
 160
 161
 162
 163 A note about MetaCommentAction:
 164 -------------------------------
 165
 166 So this class is the most interesting - a comment record is what is used to extended metafiles, to
 167 make what we call an "Enhanced Metafile". This basically gets the OutputDevice's connect metafile
 168 and adds the record via this when it runs Execute(). It doesn't actually do anything else, unlike
 169 other MetaActions which invoke functions from OutputDevice. And if there is no connect metafile in
 170 OutputDevice, then it just does nothing at all in Execute. Everything else works as normal (Read,
 171 Write, etc).
 172
 173
 174
 175 Basic pseudocode
 176 ----------------
 177
 178 The following illustrates an exceptionally basic and incomplete implementation of how to use
 179 GDIMetafile. An example can be found at vcl/workben/mtfdemo.cxx
 180
 181
 182 DemoWin::Paint()
 183 {
 184     // assume that VCL has been initialized and a new application created
 185
 186     Window* pWin = new WorkWindow();
 187     GDIMetaFile* pMtf = new GDIMetaFile();
 188
 189     SvFileStream aFileStream("example.emf", STEAM_READ);
 190
 191     ReadWindowMetafile(aFileStream, pMtf);
 192     pMtf->Play(pWin);
 193
 194 }