Class ReferenceTarget
See Also: Class ReferenceMaker, Class RefList, Class DependentEnumProc, Class RemapDir, References.
class ReferenceTarget : public ReferenceMaker
Description:
This class is used by anything that may need to have references made to it. Most plug-ins are derived from this class. This class includes methods to send notification of changes by the object, seeing which other objects in the system depend on it (reference it), and a method used to create a copy of the object ('clone' it). See the Advanced Topics section on References for an overview of the 3ds max reference architecture.
Method Groups:
The hyperlinks below jump to the start of groups of related methods within the class:
Cyclic Reference Testing / Dependency Testing
Adding / Deleting / Transfering References
Methods:
Prototype:
virtual RefResult NotifyDependents(Interval changeInt, PartID partID, RefMessage message, SClass_ID sclass=NOTIFY_ALL,BOOL propagate=TRUE, RefTargetHandle hTarg=NULL );
Remarks:
Implemented by the System.
This method broadcasts the message specified by the message parameter to all the items which reference this item.
Note the following on how reference messages propogate (that is, travel to the dependents):
When a plug-in sends a message via NotifyDependents(), the message propagates to ALL the items that reference it. And also to all the items which reference those items. And so on. The only exceptions to this are as follows:
1) The propagate parameter passed is FALSE. In that case the message only goes to the immediate dependents.
2) If the SClass_ID sclass=NOTIFY_ALL parameter limits the dependents to a certain specified Super Class.
3) If one of the items that references the plug-in processes the message inside its NotifyRefChanged() and returns REF_STOP instead of REF_SUCCEED. In this case, the message is not further propagated.
Also, whenever a message propogates, the hTarget parameter received in NotifyRefChanged() is reset to the this pointer of the immediate dependent (not the originator) who propogates the message.
Parameters:
Interval changeInt
Currently all plug-ins must pass FOREVER for this interval. This indicates the interval of time over which the change reported by the message is in effect.
PartID partID
This parameter is used to pass message specific information to the items which will receive the message. See the ReferenceMaker::NotifiyRefChanged() method for more details.
RefMessage message
The message to broadcast to all dependents. See the ReferenceMaker::NotifiyRefChanged() method for more details. See List of Reference Messages.
SClass_ID sclass=NOTIFY_ALL
This parameter defaults to NOTIFY_ALL. If this value is passed to NotifyDependents() all dependents will be notified. Other super class values may be passed to only send the message to certain items whose SuperClassID matches the one passed.
BOOL propagate=TRUE
This parameter defaults to TRUE. This indicates that the message should be sent to all 'nested' dependencies. If passed as FALSE, this parameter indicates the message should only be sent to first level dependents. Normally this should be left to default to TRUE.
RefTargetHandle hTarg=NULL
This parameter must always default to NULL.
Return Value:
This method always returns REF_SUCCEED.
Prototype:
virtual void NotifyForeground(TimeValue t)
Remarks:
Implemented by the System.
This method is called to flag dependents into the foreground. The default implementation just sends out the notification REFMSG_FLAGDEPENDENTS with PART_PUT_IN_FG as the partID. In particular, a slave controller could override this method and call its master's version of this method.
Parameters:
TimeValue t
The time to send the notification.
Prototype:
virtual void NotifyTarget(int message, ReferenceMaker* hMaker);
Remarks:
This method is available in release 4.0 and later only.
Wsed by a ReferenceMaker to send 'reverse' notification messages to its ReferenceTargets.
Parameters:
int message
The message sent to the reference target. See List of Reference Target Messages. **aztodo** link this
ReferenceMaker* hMaker
The ReferenceMaker sending the message.
Cyclic Reference Testing / Dependency Testing
Prototype:
RefResult TestForLoop(Interval refInterval, RefMakerHandle hmaker);
Remarks:
Implemented by the System.
This method may be called to test for cyclical references. Normally developers don't need to call this method since when a developer calls MakeRefByID() to make a reference it performs its own test internally and will not succeed if there is a cyclical reference being created.
Parameters:
Interval refInterval
This interval is reserved for future use. Currently any plug-in should specify FOREVER for this interval.
RefMakerHandle hmaker
The reference maker performing the loop test.
Return Value:
REF_SUCCEED if a cyclic reference would be created; otherwise REF_FAIL.
Prototype:
HasDependents()
Remarks:
Implemented by the System.
Returns nonzero if the reference target has items that reference it; otherwise 0.
Prototype:
RefList& GetRefList()
Remarks:
Implemented by the System.
Returns a list of references to this reference target.
Return Value:
List of references to this reference target.
Prototype:
void BeginDependencyTest()
Remarks:
Implemented by the System.
To see if this reference target depends on something: first call BeginDependencyTest() then call NotifyDependents() on the thing with the message REFMSG_TEST_DEPENDENCY. If EndDependencyTest() returns TRUE this target is dependent on the thing.
Prototype:
BOOL EndDependencyTest()
Remarks:
Implemented by the System.
To see if this reference target depends on something: first call BeginDependencyTest() then call NotifyDependents() on the thing with the message REFMSG_TEST_DEPENDENCY. If EndDependencyTest() returns TRUE this target is dependent on the thing.
Return Value:
Returns TRUE if the target is dependent.
Adding / Deleting / Transfering References
Prototype:
virtual void RefAdded(RefMakerHandle rm)
Remarks:
Implemented by the Plug-In.
This method is called after making a reference. If the target needs to know it can override it.
Parameters:
RefMakerHandle rm
The ReferenceMaker creating the reference.
Prototype:
RefResult DeleteAllRefsToMe();
Remarks:
Implemented by the System.
This method deletes all references to this reference target.
Return Value:
Always returns REF_SUCCEED.
Prototype:
virtual RefResult AutoDelete()
Remarks:
Implemented by the Plug-In.
This method is called when a target's last reference is deleted. Most subclasses will not need to override this. If you don't want to be deleted when the last reference is deleted, plug in a no-op.
More likely, a developer would override Animatable::DeleteThis() if they didn't want to be deleted from memory.
Return Value:
Always returns REF_SUCCEED.
Prototype:
virtual void RefDeleted()
Remarks:
Implemented by the Plug-In.
This is called after deleting a reference to a reference target, in the case that the target was not deleted. If a target needs to know, it should override this method.
Prototype:
virtual void RefDeletedUndoRedo();
Remarks:
This method is available in release 2.0 and later only.
This method is called when a reference is deleted because of an undo or a redo.
Default Implementation:
{}
Prototype:
virtual void RefAddedUndoRedo(RefMakerHandle rm);
Remarks:
This method is available in release 2.0 and later only.
This method is called when a reference is added because of an undo or a redo.
Parameters:
RefMakerHandle rm
The reference maker that is now referencing this target.
Default Implementation:
{}
Prototype:
RefResult TransferReferences(RefTargetHandle oldTarget, BOOL delOld=FALSE);
Remarks:
Implemented by the System.
This method is used to transfer all the references from oldTarget to this reference target.
Parameters:
RefTargetHandle oldTarget,
The previous reference target.
BOOL delOld=FALSE);
If this is TRUE the previous reference target is deleted.
Return Value:
Always returns REF_SUCCEED.
Prototype:
virtual int EnumDependents(DependentEnumProc* dep);
Remarks:
Implemented by the System.
This allows a reference target to enumerate all reference to it. All reference targets have a list of back pointers to entities that reference it. This method enumerates those back pointers calling the given callback object once per dependent.
Parameters:
DependentEnumProc* dep
The callback object called for each dependent.
Return Value:
Return 1 to stop the enumeration and 0 to continue.
Prototype:
virtual RefTargetHandle Clone(RemapDir &remap = NoRemap());
Remarks:
Implemented by the Plug-In.
This method is called to have the plug-in clone itself. This method should copy both the data structure and all the data residing in the data structure of this reference target. The plug-in should clone all its references as well.
Important Note: See the remarks in method BaseClone() below.
Parameters:
RemapDir &remap = NoRemap()
This class is used for remapping references during a Clone. See Class RemapDir.
Return Value:
A pointer to the cloned item.
Prototype:
virtual void BaseClone(ReferenceTarget *from, ReferenceTarget *to,RemapDir &remap);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the Plug-In.
Important Note: All plug-ins that implement a Clone() method have to call this BaseClone() method with the old and the new object as parameters. The ordering in regards to when is method is called is unimportant however it must, of course, be called after the cloned object is created.
This method allows base classes to copy their data into a new object created by the clone operation. All overwrites of BaseClone() must call the base class implementation. The base class implementation copyies the CustAttrib objects into the newly created object.
Parameters:
ReferenceTarget *from
Points to the old object to clone.
ReferenceTarget *to
Points to the new object created.
RemapDir &remap
This class is used for remapping references during a Clone. See Class RemapDir.
Prototype:
RefResult MaybeAutoDelete();
Remarks:
This method is used internally.
The following methods are for release 4.2 and above
Prototype:
virtual void* GetInterface(ULONG id)
Remarks:
Returns a pointer to the interface.
Parameters:
ULONG id
The id of the interface.
Prototype:
virtual BaseInterface* GetInterface(Interface_ID id)
Remarks:
Returns a pointer to the Base Interface for the interface ID passed.
Parameters:
Interface_ID id
The unique ID of the interface to get