vcl/README.GDIMetaFile.md

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