template<class T>
class RefMgr< T >

#include <referencemgr.h>

Inheritance diagram for RefMgr< T >:

Public Member Functions
	RefMgr ()
virtual	~RefMgr ()
virtual Class_ID	ClassID ()
	Retrieves a constant that uniquely identifies the plugin class.
virtual void	DeleteThis ()
	Deletes an instance of this class.
virtual void	Init (TNotifyCB notifyCB=NULL, void *notifyCBParam=NULL)
virtual int	Count ()
virtual int	FindRefTargetHandleIndex (RefTargetHandle rtarg)
virtual int	FindRefTargetIndex (T *pRefTarget)
virtual T *	FindRefTarget (RefTargetHandle rtarg)
virtual T *	GetRefTarget (int i)
virtual bool	AddUndo (int which, RefTargetHandle ref)
virtual bool	AddRef (T *pRefTarget)
virtual bool	RemoveRef (RefTargetHandle rtarg)
virtual bool	RemoveRef (T *pRefTarget)
virtual bool	RemoveRef (int index)
virtual void	Clear ()
virtual int	NumRefs ()
	Returns the total number of references this ReferenceMaker can hold.
virtual RefResult	DeleteReference (int which)
	Deletes the specified reference.
virtual ReferenceTarget *	GetReference (int i)
	Returns the 'i-th' reference.
virtual RefResult	NotifyRefChanged (Interval changeInt, RefTargetHandle hTarget, PartID &partID, RefMessage message)
	Receives and responds to messages.
Protected Types
typedef RefResult(*	TNotifyCB )(void cbParam, Interval changeInt, T pRefTarget, RefTargetHandle hTarger, PartID &partID, RefMessage message)
Protected Member Functions
virtual void	SetReference (int i, RefTargetHandle rtarg)
	Stores a ReferenceTarget as its 'i-th' reference`.
Protected Attributes
Tab< T * >	mRefTargetPtrs
TNotifyCB	mNotifyCB
void *	mNotifyCBParam
Friends
class	RefMgrAddDeleteRestore< T >

Member Typedef Documentation

typedef RefResult(* TNotifyCB)(void *cbParam, Interval changeInt, T *pRefTarget, RefTargetHandle hTarger, PartID &partID, RefMessage message) [protected]

Search for all occurrences

Constructor & Destructor Documentation

RefMgr ( ) [inline]

: mNotifyCB(NULL), mNotifyCBParam(NULL) { }

virtual ~RefMgr ( ) [inline, virtual]

{ DeleteAllRefs(); }

Member Function Documentation

virtual Class_ID ClassID ( ) [inline, virtual]

Search for all occurrences

Retrieves a constant that uniquely identifies the plugin class.

This method must return the unique ID for the plugin class. If two ClassIDs conflict, the system will only load the first conflicting one it finds. A program (gencid.exe) is provided to generate unique class id values.

Returns:: A class id that uniquely identifies a plugin class

See also:: Class ClassID, List of Class IDs.

Reimplemented from Animatable.

{ return Class_ID(0x7eff2f08, 0x25707aa2); }

virtual void DeleteThis ( ) [inline, virtual]

Search for all occurrences

Deletes an instance of this class.

3ds Max calls this method when it needs to delete a plugin object (an instance of a class derived from Animatable). Similarly, plugins that need to delete instances of an Animatable or a class directly derived from it via an Animatable pointer, should call this method instead of calling directly operator delete. Following these rules will ensure that the same memory manager is used to allocate and deallocate the object. The default implementation of this method deletes the object. Plugin instances that never need to be deleted from the heap can overwrite this method to do nothing.

Note:: See the method ClassDesc::Create() for details on how Max allocates plugin objects.; See ReferenceMaker::DeleteMe() and ReferenceTarget::MaybeAutoDelete() for information on how plugin instances are deleted by the system.

Remarks:: See Memory Allocation.

See also:: Plugin DLL Functions, Class ClassDesc.

Reimplemented from Animatable.

    { 
        delete this; 
    }

virtual void Init	(	TNotifyCB	notifyCB = `NULL`,
		void *	notifyCBParam = `NULL`
	)		`[inline, virtual]`

Search for all occurrences

    {
        mRefTargetPtrs.ZeroCount();
        mNotifyCB = notifyCB;
        mNotifyCBParam = notifyCBParam;
    }

virtual int Count ( ) [inline, virtual]

Search for all occurrences

{ return mRefTargetPtrs.Count(); }

virtual int FindRefTargetHandleIndex ( RefTargetHandle rtarg ) [inline, virtual]

Search for all occurrences

    {
        int n = mRefTargetPtrs.Count();
        for (int i=0; i<n; i++)
        {
            if (mRefTargetPtrs[i]->GetRefTargetHandle() == rtarg)
                return i;
        }
        return -1;
    }

virtual int FindRefTargetIndex ( T * pRefTarget ) [inline, virtual]

Search for all occurrences

    {
        int n = mRefTargetPtrs.Count();
        for (int i=0; i<n; i++)
        {
            if (mRefTargetPtrs[i]->GetRefTargetHandle() == pRefTarget->GetRefTargetHandle())
                return i;
        }
        return -1;
    }

virtual T* FindRefTarget ( RefTargetHandle rtarg ) [inline, virtual]

Search for all occurrences

    {
        int index = FindRefTargetHandleIndex(rtarg);
        return (index == -1) ? NULL : mRefTargetPtrs[index];
    }

virtual T* GetRefTarget ( int i ) [inline, virtual]

Search for all occurrences

    {
        if ( i < mRefTargetPtrs.Count() )
            return mRefTargetPtrs[i];
        else
            return NULL;
    }

virtual bool AddUndo	(	int	which,
		RefTargetHandle	ref
	)		`[inline, virtual]`

Search for all occurrences

    {
        bool undo = false;
        if (!theHold.RestoreOrRedoing()) {
            int resumeCount = 0;

            while (theHold.IsSuspended()) {
                theHold.Resume();
                ++resumeCount;
            }

            undo = theHold.Holding() != 0;
            if (undo)
                theHold.Put(new RefMgrAddDeleteRestore<T>(this, which, ref));
            
            while (--resumeCount >= 0)
                theHold.Suspend();
        }
        return undo;
    }

virtual bool AddRef ( T * pRefTarget ) [inline, virtual]

Search for all occurrences

    {
        // make sure rtarg is valid and hasn't already been referenced
        RefTargetHandle pRefTargHandle = pRefTarget->GetRefTargetHandle();
        if ( (pRefTargHandle != NULL) && (FindRefTargetIndex(pRefTarget) == -1) )
        {
            pRefTarget->SetRefTargetHandle(NULL);
            mRefTargetPtrs.Append(1, &pRefTarget);
            HoldSuspend hs;
            if ( ReplaceReference (mRefTargetPtrs.Count()-1, pRefTargHandle) != REF_SUCCEED )
            {
                pRefTarget->SetRefTargetHandle(pRefTargHandle);
                mRefTargetPtrs.Delete(mRefTargetPtrs.Count()-1, 1);
                return false;
            }
            hs.Resume();
            NotifyDependents(FOREVER, 0, REFMSG_SUBANIM_STRUCTURE_CHANGED);

            // Handle undo if we need to
            AddUndo(-1, pRefTarget->GetRefTargetHandle());
            return true;
        }
        else
            return false;
    }

virtual bool RemoveRef ( RefTargetHandle rtarg ) [inline, virtual]

Search for all occurrences

    {
        return RemoveRef( FindRefTargetHandleIndex(rtarg) );
    }

virtual bool RemoveRef ( T * pRefTarget ) [inline, virtual]

Search for all occurrences

    {
        return RemoveRef( FindRefTargetIndex(pRefTarget) );
    }

virtual bool RemoveRef ( int index ) [inline, virtual]

Search for all occurrences

    {
        if ( (index >= 0) && ( index < Count() ) )
        {
            DeleteReference(index);
            T* targ = mRefTargetPtrs[index];
            if (targ != NULL && !targ->IsHeld())
            {
                delete targ;
            }
            mRefTargetPtrs.Delete(index, 1);
            NotifyDependents(FOREVER, 0, REFMSG_SUBANIM_STRUCTURE_CHANGED);
            return true;
        }
        return false;
    }

virtual void Clear ( ) [inline, virtual]

Search for all occurrences

    {
        DeleteAllRefsFromMe();
        for ( int i = mRefTargetPtrs.Count(); --i >= 0; ) {
            T* targ = mRefTargetPtrs[i];
            if (targ != NULL && !targ->IsHeld())
            {
                delete targ;
            }
        }
        mRefTargetPtrs.ZeroCount();
        NotifyDependents(FOREVER, 0, REFMSG_SUBANIM_STRUCTURE_CHANGED);
    }

virtual int NumRefs ( ) [inline, virtual]

Search for all occurrences

Returns the total number of references this ReferenceMaker can hold.

The plugin implements this method to indicate the total number of of references it can make. This includes all references whether they are NULL (inactive) or non-NULL (active) at the time when this method is called. A plugin can hold a variable number of references, thus the return value of this method is not to be cached and reused by client code.

Returns:: The total number of references this plugin can hold. The default implementation is return 0.

Reimplemented from ReferenceMaker.

{ return Count(); }

virtual RefResult DeleteReference ( int i ) [inline, virtual]

Search for all occurrences

Deletes the specified reference.

Implemented by the System. This method deletes the reference whose virtual array index is passed. The other reference indices are not affected, i.e. the number of references is not reduced nor are they reordered in any way. Note the system calls SetReference(i, NULL) to set that reference to NULL. Also, if this is the last reference to the item, the item itself is deleted by calling its DeleteThis() method.

Parameters:

i	- The virtual array index of the reference to delete.

Returns:: This is REF_SUCCEED if the reference was deleted; otherwise it is REF_FAIL.

Reimplemented from ReferenceMaker.

                                                 {
        RefTargetHandle ref = GetReference(which);
        RefResult ret = ReferenceTarget::DeleteReference(which);
        if (ret == REF_SUCCEED) {
            AddUndo(which, ref);
        }
        return ret;
    }

virtual ReferenceTarget* GetReference ( int i ) [inline, virtual]

Search for all occurrences

Returns the 'i-th' reference.

The plugin implements this method to return its 'i-th' reference. The plug-in simply keeps track of its references using an integer index for each one. This method is normally called by the system.

Parameters:

i	- The index of the reference to retrieve. Valid values are from 0 to NumRefs()-1.

Returns:: The reference handle of the 'i-th' reference. Note that different calls to this method with the same 'i' value can result in different reference handles being retrieved, as the plugin changes the scene objects it references as its 'i-th' reference.

Reimplemented from ReferenceMaker.

    {
        if ( i < mRefTargetPtrs.Count() )
            return mRefTargetPtrs[i]->GetRefTargetHandle();
        else
            return NULL;
    }

virtual void SetReference	(	int	i,
		RefTargetHandle	rtarg
	)		`[inline, protected, virtual]`

Search for all occurrences

Stores a ReferenceTarget as its 'i-th' reference`.

The plugin implements this method to store the reference handle passed to it as its 'i-th' reference. In its implementation of this method, the plugin should simply assign the reference handle passed in as a parameter to the member variable that holds the 'i-th' reference. Other reference handling methods such as ReferenceMaker::DeleteReference(), or ReferenceMaker::ReplaceReference() should not be called from within this method. The plugin itself or other plugins should not call this method directly. The system will call this method when a new reference is created or an existing one is replaced by calling ReferenceMaker::ReplaceReference().

Parameters:

i	- The index of the reference to store. Valid values are from 0 to NumRefs()-1.
rtarg	- The reference handle to store.

Reimplemented from ReferenceMaker.

    {
        // Ignore SetReference during redo or undo, this is because the
        // RefMgrAddDeleteRestore will fix up everything.
        if (!theHold.RestoreOrRedoing()) {
            int count = mRefTargetPtrs.Count();
            assert(i < count || rtarg == NULL);
            if ( i < count )
                mRefTargetPtrs[i]->SetRefTargetHandle(rtarg);
        }
    }

virtual RefResult NotifyRefChanged	(	Interval	changeInt,
		RefTargetHandle	hTarget,
		PartID &	partID,
		RefMessage	message
	)		`[inline, virtual]`

Search for all occurrences

Receives and responds to messages.

A plugin which makes references must implement a method to receive and respond to messages broadcast by its dependents. This is done by implementing NotifyRefChanged(). The plugin developer usually implements this method as a switch statement where each case is one of the messages the plugin needs to respond to. The Method StdNotifyRefChanged calls this, which can change the partID to new value. If it doesn't depend on the particular message& partID, it should return REF_DONTCARE.

For developer that need to update a dialog box with data about an object you reference note the following related to this method: This method may be called many times. For instance, say you have a dialog box that displays data about an object you reference. This method will get called many time during the drag operations on that object. If you updated the display every time you'd wind up with a lot of 'flicker' in the dialog box. Rather than updating the dialog box each time, you should just invalidate the window in response to the NotifyRefChanged() call. Then, as the user drags the mouse your window will still receive paint messages. If the scene is complex the user may have to pause (but not let up on the mouse) to allow the paint message to go through since they have a low priority. This is the way many windows in 3ds Max work.

Parameters:

changeInt	- This is the interval of time over which the message is active. Currently, all plug-ins will receive FOREVER for this interval.
hTarget	- This is the handle of the reference target the message was sent by. The reference maker uses this handle to know specifically which reference target sent the message.
partID	- This contains information specific to the message passed in. Some messages don't use the partID at all. See the section List of Reference Messages for more information about the meaning of the partID for some common messages.
message	- The message parameters passed into this method is the specific message which needs to be handled.

Returns:: The return value from this method is of type RefResult. This is usually REF_SUCCEED indicating the message was processed. Sometimes, the return value may be REF_STOP. This return value is used to stop the message from being propagated to the dependents of the item.

Implements ReferenceMaker.

    {
        RefResult refResult(REF_SUCCEED);
        if (mNotifyCB)
        {
            T* pRefTarget = FindRefTarget(hTarget);
            refResult = mNotifyCB(mNotifyCBParam, changeInt, pRefTarget, hTarget, partID,  message);
        }

        switch (message)
        {
            case REFMSG_TARGET_DELETED:
            {
// mjm - begin - 6.20.00
                int i = FindRefTargetHandleIndex(hTarget);
                assert(i >= 0);
                if (i >= 0)
                {
                    // We need to handle undo
                    if (!AddUndo(i, hTarget))
                    {
                        delete mRefTargetPtrs[i];
                    }
                    mRefTargetPtrs.Delete(i, 1);
                }
// mjm - end
                break;
            }
        }
        return refResult;
    }