diff options
| -rw-r--r-- | vcl/README.GDIMetaFile | 416 |
1 files changed, 208 insertions, 208 deletions
diff --git a/vcl/README.GDIMetaFile b/vcl/README.GDIMetaFile index f25ca9ae3b7a..b7282a31a5d8 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); + +} |