diff options
| author | Chris Sherlock <chris.sherlock79@gmail.com> | 2014-12-02 21:35:03 +1100 |
|---|---|---|
| committer | Chris Sherlock <chris.sherlock79@gmail.com> | 2014-12-02 21:36:52 +1100 |
| commit | d1a47da4a0dcaab5edbb3e40e6ef48de1060ee85 (patch) | |
| tree | be9b0f0bcf834f8e9d3ece0a3d3c4c4927e93fa7 /vcl/README.GDIMetaFile | |
| parent | f8001effbdb9c0f09fe544b7bdbae9c15c82006f (diff) | |
vcl: document GDIMetaFile class
Change-Id: I4947726957d95586615537eb6cbcf6ed0dcb5091
Diffstat (limited to 'vcl/README.GDIMetaFile')
| -rw-r--r-- | vcl/README.GDIMetaFile | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/vcl/README.GDIMetaFile b/vcl/README.GDIMetaFile new file mode 100644 index 000000000000..f25ca9ae3b7a --- /dev/null +++ b/vcl/README.GDIMetaFile @@ -0,0 +1,208 @@ +GDIMetaFile class
+=================
+
+The GDIMetaFile class reads, writes, manipulates and replays metafiles via the VCL module.
+
+A typical usecase is to intialize 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( MAP_PIXEL )
+
+
+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
+
+
+SPECIAL RENDERING FUNCTION
+
+- makePluggableRendererAction - Create a special meaaction that delegates
+ rendering to specified service. This factory
+ function creates a MetaCommentAction that
+ delegates rendering to the specified services,
+ once played back in the metafile. Takes a
+ renderer service name string that gets an
+ awt::XGraphic on instantiation, and a graphic
+ service name string that gets the raw data on
+ instantiation.
+
+
+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 META_NULL_ACTION
+- 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
+- GetRefCount - reference counter
+- ResetRefCount - reset to 1
+- Duplicate - increment refcounter
+- Delete - delete if all instances no longer being referenced
+
+
+
+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 MetaActions 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 (TODO: put this into a unit test, or a vcl demo app).
+
+
+main()
+{
+ // assume that VCL has been initialized and a new application created
+
+ Window* pWin = new WorkWindow();
+ GDIMetaFile* pMtf = new GDIMetaFile();
+
+ ifstream aInFile;
+ aInFile.open("example.emf");
+
+ pMtf->Read(aInFile);
+ pMtf->Play(pWin);
+
+}
|