vcl/README.GDIMetaFile | 416 ++++++++++++++++++++++++------------------------- 1 file changed, 208 insertions(+), 208 deletions(-)
New commits: commit 5de46c11e48407acdeb9dbee8f80d4f6d063a0d2 Author: Khaled Hosny <[email protected]> Date: Wed Dec 3 19:42:26 2014 +0200 Donât use DOS line endings Change-Id: I55b9bad4e1f6c3519b095a09101ddcc2bca29d41 diff --git a/vcl/README.GDIMetaFile b/vcl/README.GDIMetaFile index f25ca9a..b7282a3 100644 --- a/vcl/README.GDIMetaFile +++ b/vcl/README.GDIMetaFile @@ -1,208 +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); - -} +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); + +}
_______________________________________________ Libreoffice-commits mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/libreoffice-commits
