Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
None.
Inherited By:
TStandardCanvasModelSelection
TDocumentTextSelection
TGUIEmbedderModelSelection
Purpose:
MDataExchanger is a mixin used by model selection derived classes that wish to participate in the data exchange protocol.
Instantiation:
Allocated as part of a TModelSelection derived class.
Deriving Classes:
Selections that support data exchange of models should derive from this mixin class. Derived classes must override the pure virtual functions: HandleCopyData, HandleCopyDataInto, HandleOrphanData, and HandleReplaceData.
Concurrency:
Not multithread safe.
Resource Use:
Must be used only as a mixin to a TModelSelection derived class.
Invariants:
Assert (fSelection != NIL )
MDataExchanger (TModelSelection *)
Interface Category:
API.
Purpose:
Constructs a data exchanger. The model selection portion must be passed into the constructor.
Calling Context:
Called by the derived class constructor of a class inheriting from TModelSelection and MDataExchanger.
Parameters:
- TModelSelection* -The model selection portion of the class inheriting from this mix-in.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
MDataExchanger is an abstract base class--all the constructors are protected. Do not instantiate this class.
virtual ~ MDataExchanger ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object. Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::GetSelection
- TModelSelection* GetSelection ()
- const TModelSelection* GetSelection() const
Interface Category:
API.
Purpose:
Allows commands using this protocol mixin to have access to the base model selection class.
Calling Context:
Call this function directly.
Parameters:
Return Value:
- Returns a pointer to the base model selection class.
- Returns a const pointer to the base model selection class.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::CreateAvailableTypesList
virtual void CreateAvailableTypesList (TSequenceOf < TTypeDescription > & theTypes) const
Interface Category:
API.
Purpose:
Used during type negotiation on the exporter side. This member function adds an ordered list of types that it can generate to the specified sequence. The types are ordered from most preferred to least preferred.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Used during type negotiation on the importer side. This member function examines the available types given by theChoices variable and it adds aliases to the types it can accept to theChosenTypes list. The types are ordered from most preferred to least preferred.
The default implementation chooses the type of the selected model.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
A TDocumentComponentReadEntry must be held for the component selected by this selection, because the default implementation looks up the model to get its type.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
CopyData creates a model and places a copy of the selected data into the model.
- Copies the model of the specified type. The model that it creates is of the same type as the selected model.
- Copes the model in the specified type. The type must be a type previously returned from ChooseTypes.
Calling Context:
Call this function directly.
Parameters:
- Takes no parameters.
- const TTypeDescription & theType -The type of model to create.
Return Value:
Returns a model containing the copied data.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Copies the model of the specified type. This is the same as MDataExchanger::CopyData, except that the destination model is passed in and not created by the CopyData member function.
Calling Context:
Call this function directly.
Parameters:
- TModel & theModel -The destination model to copy data into.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Removes the selected data from the model. This member function creates a separate model to contain the orphaned data and returns this model.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a model containing the orphaned selected data.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Undoes a previous orphan. The model passed in must be a model returned by a previous call to OrphanData or RedoOrphanData.
Calling Context:
Call this function directly.
Parameters:
- TModel * -The data to be returned to the target.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Removes the selected data from the model. This member function creates a separate model to contain the orphaned data and returns this model.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a model containing the orphaned selected data.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Before absorbing/replacing data, the new data must be fixed up so that the IDs associated with the anchors and links are correct. The absorb/replace will directly absorb the anchors. Model data may also have things such as IDs that require fixing up before the data can be directly absorbed. All this should be done in this member function.
Calling Context:
Call this function directly.
Parameters:
- TModel * theUnfixedUpData -The model containing the data to be fixed up.
Return Value:
Returns the model containing the fixed up data.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::AbsorbData
virtual TModel * AbsorbData (TModel * theDataToAbsorb)
Interface Category:
API.
Purpose:
Initially absorbs external data. The external data will have been fixed up by an earlier call to FixupDataBeforeAbsorbOrReplace. This member function may add the new external data into model's data without affecting the currently selected model data or it may replace the currently selected model data with this new external data.
In any case, the selection after the absorb will only specify the newly added external data.
Calling Context:
Call this function directly.
Parameters:
- TModel * theDataToAbsorb -The model data to absorb.
Return Value:
Returns a model that is given to the UndoAbsorbData if an undo is required.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Undoes the absorb external data. It is given the model returned from the original AbsorbData or RedoAbsorbData.
In any case, the selection should undo the absorb external data and return a model that will be given to the RedoAbsorbData.
Calling Context:
Call this function directly.
Parameters:
- TModel * theDataToUndoabsorb -The data return from a previous absorb.
Return Value:
Returns a model that will be given to the RedoAbsorbData if an redo is required.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
This member function is called after the UndoAbsorbData to redo the absorb external data. It is given the model that was returned from the UndoAbsorbData. The selection should reabsorb the external data and return a model that will be given to the UndoAbsorbData if another undo is required.
Calling Context:
Call this function directly.
Parameters:
- TModel * theDataToRedoAbsorb -The data returned from a previous undo absorb.
Return Value:
Returns a model that will be given to the UndoAbsorbData if an undo is required.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Initially replaces the selected data with external data. The external data will have been fixed up by an earlier call to FixupDataBeforeAbsorbOrReplace. This member function returns a model that will be given to the UndoReplaceData if an undo is required.
The selection after the replace will only specify the newly added external data.
Calling Context:
Call this function directly.
Parameters:
- TModel * theDataToReplaceSelectedData -The data used to replace the selected data.
Return Value:
Returns a model that will be given to the UndoReplaceData if an undo is required.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Undoes the replace data function. It is given the model returned from the original ReplaceData or RedoReplaceData.
In any case, the selection should undo the replace data function and return a model that will be given to the RedoReplaceData. The selection should specify the original selected data prior to the ReplaceData function.
Calling Context:
Call this function directly.
Parameters:
- TModel * theDataToUndoReplace -The model returned from a previous replace or redo replace.
Return Value:
Returns a model that will be given to the RedoAbsorbData if an redo is required.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
This member function is called after the undo the replace data function. It redoes the undone replace data with external data function. It is given the model that was returned from the UndoReplaceData. The selection should re-replace the external data and return a model that will be given to the UndoReplaceData if another undo is required.
Calling Context:
Call this function directly.
Parameters:
- TModel * theDataToRedoReplace -A model returned from a previous undo absorb.
Return Value:
Returns a model that will be given to the UndoReplaceData if an undo is required.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Selections inheriting from MDataExchanger must override this function to provide for copying of the specific model's data. This function creates the new model of the type given by the TTypeDescription and inserts copies of the selected anchors and links into the model.
Calling Context:
Called only by CopyData.
Parameters:
Return Value:
Returns an instance of a model with copied selected data.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from MDataExchanger.
Member Function: MDataExchanger::HandleCopyDataInto
virtual void HandleCopyDataInto (TModel & theModel) const
Interface Category:
API.
Purpose:
Selections inheriting from MDataExchanger must override this function to provide for copying of the specific model's data. This function takes the specified model and inserts copies of the selected anchors and links into the model.
Calling Context:
Called only by CopyDataInto.
Parameters:
- TModel & theModel -The model to receive the copied data.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from MDataExchanger.
Member Function: MDataExchanger::HandleOrphanData
virtual TModel * HandleOrphanData ()
Interface Category:
API.
Purpose:
Selections inheriting from MDataExchanger must override this function to provide for orphaning of the specific model's data. This function creates the new model of the same type as the current model and removes the selected anchors and links from the current model and inserts them into the new model.
Calling Context:
Called only by OrphanData.
Parameters:
Return Value:
Returns a new model containing the orphaned data.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from MDataExchanger.
Member Function: MDataExchanger::HandleFixupDataBeforeAbsorbOrReplace
virtual TModel * HandleFixupDataBeforeAbsorbOrReplace (TModel * theUnfixedUpData) const
Interface Category:
API.
Purpose:
This function is called by the FixupDataBeforeAbsorbOrReplace to fix up the model's data, anchors, and links. It fixes up the anchors and links so that their IDs don't clash with existing IDs and so that they point to the current model.
Calling Context:
Called only by FixupDataBeforeAbsorbOrReplace.
Parameters:
- TModel * theUnfixedUpData -The data to be fixed up.
Return Value:
Returns the specified model with its anchors and links fixed up.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleAbsorbData
virtual TModel * HandleAbsorbData (TModel * theDataToAbsorb)
Interface Category:
API.
Purpose:
Selections inheriting from MDataExchanger must override this function to provide for absorbing of the specific model's data. This function creates the new model containing undo data and absorbs the specified model's data, anchors and links into the current model.
Calling Context:
Called only by AbsorbData.
Parameters:
- TModel * theDataToAbsorb -Adopted model contained data to absorb.
Return Value:
Returns a model for undoing the absorb data command.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleReplaceData
virtual TModel * HandleReplaceData (TModel * theData)
Interface Category:
API.
Purpose:
Selections inheriting from MDataExchanger must override this function to provide for replacing of the selected model's data with the specified model's data. This function creates the new model containing undo data and absorbs the selected data with the specified model's data.
Calling Context:
Called only by ReplaceData
Parameters:
- TModel * theData -Adopt model to be used to replace selected data.
Return Value:
Returns a model for undoing the replace data command.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from MDataExchanger.
Member Function: MDataExchanger::CopyAnchorForExport
virtual TModelAnchor * CopyAnchorForExport (TModelAnchor * theSelectedAnchor, TModel & theExternalModel) const
Interface Category:
API.
Purpose:
This function is called for each anchor that needs to be copied prior to exporting.
Calling Context:
Called only by CopyData or CopyDataInto.
Parameters:
- TModelAnchor * theSelectedAnchor -The anchor to copy.
- TModel & theExternalModel -The model the anchor will be copied into.
Return Value:
Returns a copy of the selected anchor.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::FixupAnchorForImport
virtual TModelAnchor * FixupAnchorForImport (TModelAnchor* theExternalAnchor, TModel & theExternalModel) const
Interface Category:
API.
Purpose:
This function is called for each anchor that needs to be fixed-up prior to importing.
Calling Context:
Called only by AbsorbData or ReplaceData.
Parameters:
- TModelAnchor * theExternalAnchor -The anchor to be imported.
- TModel & theExternalModel -The external model from which the anchor is imported.
Return Value:
Returns a fixed up anchor.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleRedoReplaceData
virtual TModel * HandleRedoReplaceData (TModel * theDataToRedoTheReplace)
Interface Category:
API.
Purpose:
Restores the effect of an undone replace data command. The parameter to this function must have been previously returned from HandleUndoReplaceData.
Calling Context:
Called only from RedoReplaceData.
Parameters:
- TModel * theDataToRedoTheReplace -The data to be used to redo the replace command.
Return Value:
Returns a model to use for undoing the redo.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleUndoReplaceData
virtual TModel * HandleUndoReplaceData (TModel * theDataToUndoTheReplace)
Interface Category:
API.
Purpose:
Undoes the effect of a replace data command. The parameter to this function must have been previously returned from HandleReplaceData.
Calling Context:
Called only from UndoReplaceData.
Parameters:
- TModel * theDataToUndoTheReplace -The data to be used to undo the replace command.
Return Value:
Returns a model to use for redoing the undo.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleRedoAbsorbData
virtual TModel * HandleRedoAbsorbData (TModel * theDataToRedoTheAbsorb)
Interface Category:
API.
Purpose:
Restores the effect of an undone absorb data command. The parameter to this function must have been previously returned from HandleUndoAbsorbData.
Calling Context:
Called only from RedoAbsorbData.
Parameters:
- TModel * theDataToRedoTheAbsorb -The data to be used to redo the undone absorb data command.
Return Value:
Returns a model to be used to undo the redo.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleUndoAbsorbData
virtual TModel * HandleUndoAbsorbData (TModel * theDataToUndoTheAbsorb)
Interface Category:
API.
Purpose:
Undoes the effect of an absorb data command. The parameter to this function must have been previously returned from HandleAbsorbData.
Calling Context:
Called only from UndoAbsorbData.
Parameters:
- TModel * theDataToUndoTheAbsorb -The data to be used to undo the absorb data command.
Return Value:
Returns a model to be used to redo the undo.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleRedoOrphanData
virtual TModel * HandleRedoOrphanData ()
Interface Category:
API.
Purpose:
Restores the effect of an undone orphan data command.
Calling Context:
Called only from RedoOrphanData.
Parameters:
Return Value:
Returns a model to be used to undo the redo.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MDataExchanger::HandleUndoOrphanData
virtual void HandleUndoOrphanData (TModel *)
Interface Category:
API.
Purpose:
Undoes the effect of an orphan data command. The parameter to this function must have been previously returned from OrphanData.
Calling Context:
Called only from UndoOrphanData.
Parameters:
- TModel * -The data to be used to undo the orphan data.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
MDataExchanger & operator =(const MDataExchanger &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
Return Value:
Returns a const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.