IReferenceConverter Class Reference

#include <IReferenceConverter.h>

Inheritance diagram for IReferenceConverter:

Public Types
enum	{ kDefaultIID = IID_IREFERENCECONVERTER }

Public Member Functions
virtual bool16	CanConvert (ClassID clsID)=0
virtual UID	ConvertReference (IDataBase *sourceDB, UID convertThis, IDataBase *targetDB, IPMUnknown *pmobject)=0
virtual bool16	ConvertAlways () const =0
virtual UID	GetReference (IDataBase *sourceDB, UID convertThis, IDataBase *targetDB) const =0
virtual bool16	IsMappingReference (IDataBase *sourceDB, UID convertThis, IDataBase *targetDB) const =0
virtual UID	MapReference (IDataBase *sourceDB, UID convertThis, IDataBase *targetDB, IPMUnknown *pmobject)=0
virtual UID	GetMappedReference (IDataBase *sourceDB, UID convertThis, IDataBase *targetDB)=0
Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0
virtual void	AddRef () const =0
virtual void	Release () const =0

Detailed Description

This interface is used for controlling how UIDs are copied from one document or context into another. During a copy, when a UID is encountered, the copy code looks to see if the UID has already been copied within that context. If so, it uses the destination UID that got generated when the object was copied earlier. Otherwise, it gets the class of the UID, and looks for a reference converter that can copy the object. If no reference converter is found, the object will not be copied, and the resulting containing object will have kInvalidUID.

Reference converters are used for copying named colors and styles; rather than always generating a new color, the color reference converter looks first to see if it can find a color of the same name in the target document. If so, it uses that color, and otherwise it fires a create color command which creates the new color and adds it to the swatch list. This is just one example; there are lots of cases where it is useful for an object to be able to define how it is copied.

Reference converters are services (kReferenceConverterService) and IReferenceConverter is the interface used for them.

See Also

IXReferenceUID

Member Function Documentation

virtual bool16 IReferenceConverter::CanConvert ( ClassID  clsID )

pure virtual

Return kTrue if the converter is capable of converting objects of the class clsID.

Parameters

clsID

the class of the object being copied

Returns

kTrue if this reference converters handles the object type

Implemented in PstLstReferenceConverter, and CReferenceConverter.

virtual bool16 IReferenceConverter::ConvertAlways ( ) const

pure virtual

Return kTrue if the converter should be called to convert every time. The default return value should be kFalse to allow K2 recognize that an item has already been converted and that when it encounters other references to the same item, it can simply use the result of the previous conversion.

Implemented in PstLstReferenceConverter, and CReferenceConverter.

virtual UID IReferenceConverter::ConvertReference ( IDataBase *  sourceDB, UID  convertThis, IDataBase *  targetDB, IPMUnknown *  pmobject  )

pure virtual

Convert the UID from a reference to a uid in the source database, to a reference to a UID in the target database. This may cause changes to the target database.

Parameters

sourceDB	the database we're copying from
convertThis	the object we're copying
targetDB	the database we're copying to
pmobject	a helper object (whatever pmobject was passed into ScrapUtils::CopyObjects or whatever other calling code set up the stream)

Returns

the UID of the matching object in the target database

Implemented in PstLstReferenceConverter, and CReferenceConverter.

virtual UID IReferenceConverter::GetMappedReference ( IDataBase *  sourceDB, UID  convertThis, IDataBase *  targetDB  )

pure virtual

Like MapReference() it maps the UID from sourceDB to targetDB but it doesn't create a new UID in the targetDB if it couldn't convert it. Instead it returns kInvalidUID.

Implemented in CReferenceConverter.

virtual UID IReferenceConverter::GetReference ( IDataBase *  sourceDB, UID  convertThis, IDataBase *  targetDB  ) const

pure virtual

Like ConvertReference() it converts the UID from sourceDB to targetDB but it doesn't create a new UID in the targetDB if it couldn't convert it. Instead it returns kInvalidUID. This method is used i.e. by Find/Change of UID based text attributes (language, font, color).

Implemented in PstLstReferenceConverter, and CReferenceConverter.

virtual bool16 IReferenceConverter::IsMappingReference ( IDataBase *  sourceDB, UID  convertThis, IDataBase *  targetDB  ) const

pure virtual

Returns kTrue if reference conversion is being done for the purpose of mapping references (e.g. style mapping). The default return value for most reference converter should be kFalse. Only converters which will be doing mapping of reference for the passed "convertThis" UID, should return kTrue

Parameters

sourceDB	the database we're copying from
convertThis	the object whose reference we intend to convert
targetDB	the database we're copying to.

Returns

kTrue if we are mapping the object from source to target DB.

Implemented in CReferenceConverter.

virtual UID IReferenceConverter::MapReference ( IDataBase *  sourceDB, UID  convertThis, IDataBase *  targetDB, IPMUnknown *  pmobject  )

pure virtual

Map the UID from a reference to a uid in the source database, to a reference to a UID in the target database. This may cause changes to the target database.

Parameters

sourceDB	the database we're copying from
convertThis	the object we're mapping
targetDB	the database we're copying to
pmobject	a helper object (whatever pmobject was passed into ScrapUtils::CopyObjects or whatever other calling code set up the stream)

Returns

the UID of the mapped object in the target database

Implemented in CReferenceConverter.