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 usecase is to intialize 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( MAP_PIXEL )
  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 SPECIAL RENDERING FUNCTION
 112
 113 - makePluggableRendererAction               - Create a special meaaction that delegates
 114                                               rendering to specified service. This factory
 115                                               function creates a MetaCommentAction that
 116                                               delegates rendering to the specified services,
 117                                               once played back in the metafile. Takes a
 118                                               renderer service name string that gets an
 119                                               awt::XGraphic on instantiation, and a graphic
 120                                               service name string that gets the raw data on
 121                                               instantiation.
 122
 123
 124 Related classes
 125 ---------------
 126
 127 MetaAction: a base class used by all records. It implements a command-like pattern, and also
 128 acts as a prototype for other actions.
 129
 130
 131 CONSTRUCTORS AND DESTRUCTORS
 132
 133 - MetaAction()                              - default constructor, sets mnRefCount to 1 and
 134                                               mnType, in this case MetaActionType::NONE
 135 - MetaAction(sal_uInt16 nType)              - virtual constructor, sets mnType to nType, and
 136                                               mnRefCount to 1
 137 - ~MetaAction
 138
 139
 140 COMMAND FUNCTION
 141
 142 - Execute(OutputDevice*)                    - execute the functionality of the record to the
 143                                               OutputDevice. Part of command pattern.
 144
 145
 146 FACTORY FUNCTION
 147
 148 - Clone()                                   - prototype clone function
 149
 150
 151 MANIPULATION FUNCTIONS
 152
 153 - Move(long nHorzMove, long nVerMove)
 154 - Scale(double fScaleX, double fScaleY)
 155
 156
 157 READ AND WRITE FUNCTIONS
 158
 159 - Read
 160 - Write
 161 - ReadMetaAction                            - a static function, only used to determine which
 162                                               MetaAction to call on to read the record, which
 163                                               means that this is the function that must be used.
 164
 165
 166 INTROSPECTIVE FUNCTIONS
 167
 168 - GetType
 169 - GetRefCount                               - reference counter
 170 - ResetRefCount                             - reset to 1
 171 - Duplicate                                 - increment refcounter
 172 - Delete                                    - delete if all instances no longer being referenced
 173
 174
 175
 176 A note about MetaCommentAction:
 177 -------------------------------
 178
 179 So this class is the most interesting - a comment record is what is used to extended metafiles, to
 180 make what we call an "Enhanced Metafile". This basically gets the OutputDevice's connect metafile
 181 and adds the record via this when it runs Execute(). It doesn't actually do anything else, unlike
 182 other MetaActions which invoke functions from OutputDevice. And if there is no connect metafile in
 183 OutputDevice, then it just does nothing at all in Execute. Everything else works as normal (Read,
 184 Write, etc).
 185
 186
 187
 188 Basic pseudocode
 189 ----------------
 190
 191 The following illustrates an exceptionally basic and incomplete implementation of how to use
 192 GDIMetafile. An example can be found at vcl/workben/mtfdemo.cxx
 193
 194
 195 DemoWin::Paint()
 196 {
 197     // assume that VCL has been initialized and a new application created
 198
 199     Window* pWin = new WorkWindow();
 200     GDIMetaFile* pMtf = new GDIMetaFile();
 201
 202     SvFileStream aFileStream("example.emf", STEAM_READ);
 203
 204     ReadWindowMetafile(aFileStream, pMtf);
 205     pMtf->Play(pWin);
 206
 207 }