IRefTargContainer Class Reference
 
 
 
IRefTargContainer Class Reference

This reference page is linked to from the following overview topics: Reference System Best Practices, Managing Variable Number of References.


#include <IRefTargContainer.h>

Inheritance diagram for IRefTargContainer:
ReferenceTarget ReferenceMaker Animatable InterfaceServer Noncopyable MaxHeapOperators MaxHeapOperators IIndirectRefTargContainer

Class Description

Container that handles references to ReferenceTargets.

This is the interface for a container that references a variable number of ReferenceTarget objects.

3ds Max's implementation of this interface persists itself and its operations support being undone/redone. Plugins that need to store a variable number of references to other plugin objects should create an instance of this container type and make a reference to it.

The code below shows how to create an instance of 3ds Max's implementation of this interface:

Note:
When this container points to a ReferenceTarget, and that RefTarg deletes itself, the corresponding reference slot is nulled out, but not deleted. Therefore the number of items reported by NumRefs() and GetNumItems()) will not shrink. For example: If ten ReferenceTargets are added to the container, and then each reftag is deleted, the container will still report ten references! The only way to shrink the count of the real number of references used is to call RemoveItem().
See also:
IIndirectRefTargContainer, IRefTargMonitorClass, INodeMonitor

Public Member Functions

virtual int  GetNumItems ()=0
  Returns the number of items in the container.
virtual ReferenceTarget GetItem (int i)=0
  Returns the i-th item, NULL if i is out of range.
virtual int  AppendItem (ReferenceTarget *ref)=0
  Adds an item at the end of the container.
virtual void  SetItem (int i, ReferenceTarget *ref)=0
  Sets the value of the i-th container item.
virtual int  InsertItem (int i, ReferenceTarget *ref)=0
  Inserts specified item at i-th place into the container.
virtual void  RemoveItem (int i)=0
  Removes the i-th item from the container.

Member Function Documentation

virtual int GetNumItems ( ) [pure virtual]

Returns the number of items in the container.

Returns:
The number of items in the container.
virtual ReferenceTarget* GetItem ( int  i ) [pure virtual]

Returns the i-th item, NULL if i is out of range.

Parameters:
i The index of the item to return. Must be in range [0, GetNumItems()-1]
Returns:
The i-th item, or NULL if index is out of range.
virtual int AppendItem ( ReferenceTarget ref ) [pure virtual]

Adds an item at the end of the container.

Parameters:
ref The item to be added
Returns:
The index of the newly added item.
virtual void SetItem ( int  i,
ReferenceTarget ref 
) [pure virtual]

Sets the value of the i-th container item.

Can be used to append more than one item to the container at a time. For example: It is possible to call this method on an empty container, passing in an integer value of, say 10. After doing this, the container will return 11 from the GetNumItems() and NumRefs() method.

Parameters:
i - The index of the item to set. Must be >= 0. If i is greater than or equal to the current number of items, the container will be resized, with NULL items added as necessary.
ref - The item to set as the i-th item.
virtual int InsertItem ( int  i,
ReferenceTarget ref 
) [pure virtual]

Inserts specified item at i-th place into the container.

Parameters:
i - The index where the item should be inserted. Must be in range [0, GetNumItems()], otherwise i is truncated to fit in this range. When i is GetNumItems(), the item is appended to the end of the container.
ref - The item to be inserted.
Returns:
Index where the item has been inserted.
virtual void RemoveItem ( int  i ) [pure virtual]

Removes the i-th item from the container.

De-references the i-th item and removes it from the container, thus effectively changing the number of items the container reports to have via GetNumItems().

Note:
When removing more than one item from the container, iterate from high index to low index.
Parameters:
i - The index of the item to be removed. Must be in range [0, GetNumItems()-1].