diff options
Diffstat (limited to 'vcl/README.GDIMetaFile.md')
| -rw-r--r-- | vcl/README.GDIMetaFile.md | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/vcl/README.GDIMetaFile.md b/vcl/README.GDIMetaFile.md new file mode 100644 index 0000000000..386a91e2ad --- /dev/null +++ b/vcl/README.GDIMetaFile.md @@ -0,0 +1,182 @@ +# GDIMetaFile class + +The `GDIMetaFile` class reads, writes, manipulates and replays metafiles via the +`VCL` module. + +A typical use case is to initialize a new `GDIMetaFile`, open the actual stored +metafile and read it in via `GDIMetaFile::Read( aIStream )`. This reads in the +metafile into the `GDIMetafile` object - it can read in an old-style `VCLMTF` +metafile (back in the days that Microsoft didn't document the metafile format +this was used), as well as EMF+ files - and adds them to a list (vector) of +`MetaActions`. You can also populate your own `GDIMetaFile` via `AddAction()`, +`RemoveAction()`, `ReplaceAction()`, etc. + +Once the `GDIMetafile` object is read to be used, you can "play" the metafile, +"pause" it, "wind forward" or "rewind" the metafile. The metafile can be moved, +scaled, rotated and clipped, as well have the colours adjusted or replaced, or +even made monochrome. + +The GDIMetafile can be used to get an `OutputDevice`'s metafile via the +`Linker()` and `Record()` functions. + +## Using GDIMetafile + +First, create a new `GDIMetafile`, this can be done via the default constructor. +It can then be constructed manually, or you can use `Record()` on an +`OutputDevice` to populate the `GDIMetaFile`, or of course you can read it from +file with `Read()`. From here you can then elect to manipulate the metafile, or +play it back to another `GDIMetafile` or to an `OutputDevice` via `Play()`. To +store the file, use `Write()`. + +### CONSTRUCTORS AND DESTRUCTORS + +- `GDIMetaFile` +- `GDIMetaFile( cosnt GDIMetaFile& rMtf )` - copy constructor +- `~GDIMetaFile` + +### OPERATORS + +- `operator =` +- `operator ==` +- `operator !=` + +### RECORDING AND PLAYBACK FUNCTIONS + +- `Play(GDIMetaFile&, size_t)` - play back metafile into another + metafile up to position +- `Play(OutputDevice*, size_t)` - play back metafile into + `OutputDevice` up to position +- `Play(OutputDevice*, Point, Size, size_t)` - play back metafile into + `OutputDevice` at a particular + location on the `OutputDevice`, up + to the position in the metafile +- `Pause` - pauses or continues the playback +- `IsPause` +- `Stop` - stop playback fully +- `WindStart` - windback to start of the metafile +- `windPrev` - windback one record +- `GetActionSize` - get the number of records in the + metafile + + +### METAFILE RECORD FUNCTIONS + +- `FirstAction` - get the first metafile record +- `NextAction` - get the next metafile record from + the current position +- `GetAction(size_t)` - get the metafile record at + location in file +- `GetCurAction` - get the current metafile record +- `AddAction(MetaAction*)` - appends a metafile record +- `AddAction(MetaAction*, size_t)` - adds a metafile record to a + particular location in the file +- `RemoveAction` - removes record at file location +- `Clear` - first stops if recording, then + removes all metafile records +- `push_back` - pushes back, basically a thin + wrapper to the metafile record list + + +### READ AND WRITING + +- `Read` +- `Write` +- `GetChecksum` +- `GetSizeBytes` + + +### DISPLACEMENT FUNCTIONS + +- `Move( long nX, long nX)` +- `Move( long nX, long nX, long nDPIX, long nDPIY )` - Move method getting + specifics how to handle + MapMode( MapUnit::MapPixel ) + + +### TRANSFORMATION FUNCTIONS + +- `Scale( double fScaleX, double fScaleY )` +- `Scale( const Fraction& rScaleX, const Fraction& rScaleY )` +- `Mirror` +- `Rotate( long nAngle10 )` +- `Clip( const Rectangle& )` + + +### COLOR ADJUSTMENT FUNCTIONS + +- `Adjust` - change luminance, contrast, + gamma and RGB via a percentage +- `Convert` - colour conversion +- `ReplaceColors` +- `GetMonochromeMtf` + +## Related classes + +`MetaAction`: a base class used by all records. It implements a command-like +pattern, and also acts as a prototype for other actions. + +### CONSTRUCTORS AND DESTRUCTORS + +- `MetaAction()` - default constructor, sets mnRefCount to 1 and + mnType, in this case MetaActionType::NONE +- `MetaAction(sal_uInt16 nType)` - virtual constructor, sets mnType to nType, and + mnRefCount to 1 +- `~MetaAction` + +### COMMAND FUNCTION + +- `Execute(OutputDevice*)` - execute the functionality of the record to the + OutputDevice. Part of command pattern. +### FACTORY FUNCTION + +- `Clone()` - prototype clone function + +### MANIPULATION FUNCTIONS + +- `Move(long nHorzMove, long nVerMove)` +- `Scale(double fScaleX, double fScaleY)` + + +### READ AND WRITE FUNCTIONS + +- `Read` +- `Write` +- `ReadMetaAction` - a static function, only used to determine which + MetaAction to call on to read the record, which + means that this is the function that must be used. + +### INTROSPECTIVE FUNCTIONS + +- `GetType` + +### A note about MetaCommentAction + +So this class is the most interesting - a comment record is what is used to +extended metafiles, to make what we call an "Enhanced Metafile". This basically +gets the `OutputDevice`'s connect metafile and adds the record via this when it +runs `Execute()`. It doesn't actually do anything else, unlike other +`MetaAction`s which invoke functions from `OutputDevice`. And if there is no +connect metafile in `OutputDevice`, then it just does nothing at all in Execute. +Everything else works as normal (Read, Write, etc). + +## Basic pseudocode + +The following illustrates an exceptionally basic and incomplete implementation +of how to use `GDIMetafile`. An example can be found at +`vcl/workben/mtfdemo.cxx` + +``` +DemoWin::Paint() +{ + // assume that VCL has been initialized and a new application created + + Window* pWin = new WorkWindow(); + GDIMetaFile* pMtf = new GDIMetaFile(); + + SvFileStream aFileStream("example.emf", STEAM_READ); + + ReadWindowMetafile(aFileStream, pMtf); + pMtf->Play(pWin); + +} +``` |