BaseContainer Class Reference

#include <c4d_basecontainer.h>

Detailed Description

A container is a collection of individual values. Each value has its own ID and type. Container can also carry any number of child containers.
90% of Cinema 4D's internal values are stored in containers and all messages are working with container, so this class is an essential part of the SDK.

Containers can store any GeData type, including custom data types. Use GetCustomDataType() to access these values in a safe manner.

It is recommended to use the available containers to store your own values as well. That way they will be automatically saved.
However, to store values in the top level of for example an object container, use a sub-container with a unique id from http://www.plugincafe.com. Inside this sub-container use whatever ids.

Warning
Keep in mind that there is no guarantee for a value to be in the container. Use default values whenever possible when accessing container's ID data.
Use the typed access methods (for example GetBool()) whenever possible, instead of the low-level GetData().
Once a container value has been set using one type you must neither try to access it using another type, nor overwrite it with a value of another type! Using the wrong access will not crash, but it is illegal.

Private Attributes

void * dummy1
 
Int dummy2
 
Int32 dummy3
 
Int32 dummy4
 
Int32 dummy5
 

Constructor/Destructor

 BaseContainer ()
 
 BaseContainer (Int32 id)
 
 BaseContainer (const BaseContainer &n)
 
 ~BaseContainer (void)
 

Assign/Clone/Copy

const BaseContaineroperator= (const BaseContainer &n)
 
BaseContainerGetClone (COPYFLAGS flags, AliasTrans *trans) const
 
Bool CopyTo (BaseContainer *dst, COPYFLAGS flags, AliasTrans *trans) const
 

Flush All

void FlushAll (void)
 

Id

Int32 GetId () const
 
void SetId (Int32 c_id)
 

Dirty

UInt32 GetDirty () const
 

Remove Data/Index

Bool RemoveData (Int32 id)
 
Bool RemoveIndex (Int32 i)
 

Find Index / Get Index Id

Int32 FindIndex (Int32 id, GeData **ppData=nullptr) const
 
Int32 GetIndexId (Int32 index) const
 

Get Data Pointer(s)

const GeDataGetDataPointer (Int32 id) const
 
void GetDataPointers (const Int32 *ids, Int32 cnt, const GeData **data) const
 

Data

GeDataGetIndexData (Int32 index) const
 
GeDataInsData (Int32 id, const GeData &n)
 
GeDataInsDataAfter (Int32 id, const GeData &n, GeData *last)
 
GeDataSetData (Int32 id, const GeData &n)
 
const GeDataGetData (Int32 id) const
 

Equal/Not Equal Operators

Bool operator== (const BaseContainer &d) const
 
Bool operator!= (const BaseContainer &d) const
 

Get Data

Bool GetBool (Int32 id, Bool preset=false) const
 
Int32 GetInt32 (Int32 id, Int32 preset=0) const
 
UInt32 GetUInt32 (Int32 id, UInt32 preset=0) const
 
Int64 GetInt64 (Int32 id, Int64 preset=0) const
 
UInt64 GetUInt64 (Int32 id, UInt64 preset=0) const
 
Float GetFloat (Int32 id, Float preset=0.0) const
 
void * GetVoid (Int32 id, void *preset=nullptr) const
 
void * GetMemoryAndRelease (Int32 id, Int &count, void *preset=nullptr)
 
void * GetMemory (Int32 id, Int &count, void *preset=nullptr) const
 
Vector GetVector (Int32 id, const Vector &preset=Vector()) const
 
Matrix GetMatrix (Int32 id, const Matrix &preset=Matrix()) const
 
String GetString (Int32 id, const String &preset=String()) const
 
C4DUuid GetUuid (Int32 id, const C4DUuid &preset=C4DUuid(DC)) const
 
Filename GetFilename (Int32 id, const Filename &preset=Filename()) const
 
BaseTime GetTime (Int32 id, const BaseTime &preset=BaseTime()) const
 
BaseContainer GetContainer (Int32 id) const
 
BaseContainerGetContainerInstance (Int32 id)
 
const BaseContainerGetContainerInstance (Int32 id) const
 
BaseList2DGetLink (Int32 id, const BaseDocument *doc, Int32 instanceof=0) const
 
BaseObjectGetObjectLink (Int32 id, const BaseDocument *doc) const
 
BaseMaterialGetMaterialLink (Int32 id, const BaseDocument *doc) const
 
BaseLinkGetBaseLink (Int32 id) const
 
const CustomDataTypeGetCustomDataType (Int32 id, Int32 datatype) const
 

Get Type

Int32 GetType (Int32 id) const
 

Set Data

void SetBool (Int32 id, Bool b)
 
void SetInt32 (Int32 id, Int32 l)
 
void SetUInt32 (Int32 id, UInt32 l)
 
void SetInt64 (Int32 id, Int64 l)
 
void SetUInt64 (Int32 id, UInt64 l)
 
void SetFloat (Int32 id, Float r)
 
void SetVoid (Int32 id, void *v)
 
void SetMemory (Int32 id, void *mem, Int count)
 
void SetVector (Int32 id, const Vector &v)
 
void SetMatrix (Int32 id, const Matrix &m)
 
void SetString (Int32 id, const String &s)
 
void SetUuid (Int32 id, const C4DUuid &u)
 
void SetFilename (Int32 id, const Filename &f)
 
void SetTime (Int32 id, const BaseTime &b)
 
void SetContainer (Int32 id, const BaseContainer &s)
 
void SetLink (Int32 id, C4DAtomGoal *link)
 

Merge Container

void MergeContainer (const BaseContainer &src)
 

Get/Set Parameter

Bool GetParameter (const DescID &id, GeData &t_data) const
 
Bool SetParameter (const DescID &id, const GeData &t_data)
 

Sort

void Sort ()
 

Constructor & Destructor Documentation

§ BaseContainer() [1/3]

Default constructor. Creates an empty container with ID 0.

§ BaseContainer() [2/3]

BaseContainer ( Int32  id)
explicit

Creates a container with a specific id.

Parameters
[in]idThe container ID.

§ BaseContainer() [3/3]

BaseContainer ( const BaseContainer n)

Copy constructor. Creates a new container with all the IDs and values from the source one.

Parameters
[in]nThe source container.

§ ~BaseContainer()

~BaseContainer ( void  )

Destructor.

Member Function Documentation

§ operator=()

const BaseContainer& operator= ( const BaseContainer n)

Assignment operator. Copies all values from the source container.

Parameters
[in]nThe source container.
Returns
The assigned source container to the left-operand container.

§ GetClone()

BaseContainer* GetClone ( COPYFLAGS  flags,
AliasTrans trans 
) const

Retrieves a copy of the container including all values.

Parameters
[in]flagsThe flags for the clone: COPYFLAGS
[in]transAn alias translator for the operation. Can be nullptr. The caller owns the pointed alias translator.
Returns
The cloned container. The caller owns the pointed container.

§ CopyTo()

Bool CopyTo ( BaseContainer dst,
COPYFLAGS  flags,
AliasTrans trans 
) const

Copies the container values into the destination container dst.

Parameters
[out]dstThe destination container. The caller owns the pointed container.
[in]flagsThe flags for the clone: COPYFLAGS
[in]transAn alias translator for the operation. Can be nullptr. The caller owns the pointed alias translator.
Returns
true if successful, otherwise false.

§ FlushAll()

void FlushAll ( void  )

Clears all values in the container. The container ID is not changed.

§ GetId()

Int32 GetId ( ) const

Gets the ID of the container.

Returns
The container ID.

§ SetId()

void SetId ( Int32  c_id)

Sets the ID of the container.

Parameters
[in]c_idThe container ID.

§ GetDirty()

UInt32 GetDirty ( ) const

Gets the dirty count. It is incremented when the container changes so it can be used to check if the container has changed.

Returns
The dirty counter.

§ RemoveData()

Bool RemoveData ( Int32  id)

Removes the first data item with the specified id.

Parameters
[in]idThe ID of the value to be removed.
Returns
true if any value was removed, otherwise false.

§ RemoveIndex()

Bool RemoveIndex ( Int32  i)

Removes the data item at the specified index i.

Parameters
[in]iThe index of the value to be removed.
Returns
true if any value was removed, otherwise false.

§ FindIndex()

Int32 FindIndex ( Int32  id,
GeData **  ppData = nullptr 
) const

Gets the index for the value with the specified id. ppData is optionally assigned the data of the specified id.

Parameters
[in]idThe ID of the value.
[out]ppDataAssigned the data of the specified id, if not nullptr.
Returns
The index of the value, or NOTOK if such value does not exists.

§ GetIndexId()

Int32 GetIndexId ( Int32  index) const

Gets the ID of the element at the specified index.
Can be used to browse through the container:

Int32 i = 0;
while (true)
{
id = GetIndexId(i++);
if (id==NOTOK) break;
...
}
Parameters
[in]indexThe index of the value.
Returns
The ID of the value, or NOTOK if it does not exist.

§ GetDataPointer()

const GeData* GetDataPointer ( Int32  id) const

Retrieves a pointer to directly access the data (Read-only).

Parameters
[in]idThe ID of the data.
Returns
A pointer to the data (Read-only). The container owns the pointed data.

§ GetDataPointers()

void GetDataPointers ( const Int32 ids,
Int32  cnt,
const GeData **  data 
) const

Retrieves an array of pointers to directly access the data (Read-only).

Parameters
[out]idsAssigned a pointer to the array of data IDs. The container owns the pointed array.
[in]cntThe number of array elements.
[out]dataAssigned a pointer to the data pointer array. The container owns the pointed array.

§ GetIndexData()

GeData* GetIndexData ( Int32  index) const

Retrieves the data for the element at index.

Parameters
[in]indexThe index of the element.
Returns
The data, or nullptr if no data was found. The container owns the pointed data. Must not be changed!

§ InsData()

GeData* InsData ( Int32  id,
const GeData n 
)

Inserts an arbitrary data at the specified id.

Note
Does not check if the ID already exists in the container.
Parameters
[in]idThe ID to insert at.
[in]nThe data to insert.
Returns
The inserted data. The container owns the pointed data.

§ InsDataAfter()

GeData* InsDataAfter ( Int32  id,
const GeData n,
GeData last 
)

Inserts an arbitrary data at the specified id after last.

Parameters
[in]idThe ID to insert at.
[in]nThe data to insert.
[in]lastThe data to insert after. The container owns the pointed data.
Returns
The inserted data. The container owns the pointed data.

§ SetData()

GeData* SetData ( Int32  id,
const GeData n 
)

Sets an arbitrary data at the specified id. If a value exists under the same ID, its content will be changed.

Parameters
[in]idThe ID of the element to set.
[in]nThe data to set.
Returns
The data set, or a DA_NIL data if it was not found.

§ GetData()

const GeData& GetData ( Int32  id) const

Retrieves the data for an element at the specified id.

Parameters
[in]idThe ID of the element.
Returns
The data, or a DA_NIL data if it was not found.

§ operator==()

Bool operator== ( const BaseContainer d) const

Equality operator. Checks if the containers have the same IDs, the same values and all values are equal.

Parameters
[in]dThe container to compare against.
Returns
true if the containers have the same IDs, the same values and all values are equal, otherwise false.

§ operator!=()

Bool operator!= ( const BaseContainer d) const

Not equal operator. Checks if the containers have different IDs, different values or values are different.

Parameters
[in]dThe container to compare against.
Returns
true if the containers have different IDs, different values or values are different, otherwise false.

§ GetBool()

Bool GetBool ( Int32  id,
Bool  preset = false 
) const

Gets the Bool value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetInt32()

Int32 GetInt32 ( Int32  id,
Int32  preset = 0 
) const

Gets the Int32 value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetUInt32()

UInt32 GetUInt32 ( Int32  id,
UInt32  preset = 0 
) const

Gets the UInt32 value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetInt64()

Int64 GetInt64 ( Int32  id,
Int64  preset = 0 
) const

Gets the Int64 value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetUInt64()

UInt64 GetUInt64 ( Int32  id,
UInt64  preset = 0 
) const

Gets the UInt64 value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetFloat()

Float GetFloat ( Int32  id,
Float  preset = 0.0 
) const

Gets the Float value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetVoid()

void* GetVoid ( Int32  id,
void *  preset = nullptr 
) const

Gets the void* value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value, or preset if it does not exist.

§ GetMemoryAndRelease()

void* GetMemoryAndRelease ( Int32  id,
Int count,
void *  preset = nullptr 
)

Gets the memory buffer at the specified id.

Note
In this version of GetMemory() the caller takes over the ownership of the memory block.
The memory block must be allocated with NewMem() and deallocated with DeleteMem().
Parameters
[in]idThe ID of the requested value.
[out]countAssigned the number of bytes in the memory buffer returned.
[in]presetReturned if the value is not available.
Returns
The memory buffer, or preset if it does not exist. The caller takes over the ownership of the memory block.

§ GetMemory()

void* GetMemory ( Int32  id,
Int count,
void *  preset = nullptr 
) const

Gets the memory buffer at the specified id.

Parameters
[in]idThe ID of the requested value.
[out]countAssigned the number of bytes in the memory buffer returned.
[in]presetReturned if the value is not available.
Returns
The memory buffer, or preset if it does not exist. The caller takes over the ownership of the memory block.

§ GetVector()

Vector GetVector ( Int32  id,
const Vector preset = Vector() 
) const

Gets the Vector value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetMatrix()

Matrix GetMatrix ( Int32  id,
const Matrix preset = Matrix() 
) const

Gets the Matrix value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetString()

String GetString ( Int32  id,
const String preset = String() 
) const

Gets the String value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetUuid()

C4DUuid GetUuid ( Int32  id,
const C4DUuid preset = C4DUuid(DC) 
) const

Gets the C4DUuid value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetFilename()

Filename GetFilename ( Int32  id,
const Filename preset = Filename() 
) const

Gets the Filename value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetTime()

BaseTime GetTime ( Int32  id,
const BaseTime preset = BaseTime() 
) const

Gets the BaseTime value at the specified id.

Parameters
[in]idThe ID of the requested value.
[in]presetReturned if the value is not available.
Returns
The value.

§ GetContainer()

BaseContainer GetContainer ( Int32  id) const

Gets a copy of the sub-container at the specified id.

Parameters
[in]idThe ID of the requested sub-container.
Returns
The sub-container, or an empty container if it does not exist.

§ GetContainerInstance() [1/2]

BaseContainer* GetContainerInstance ( Int32  id)

Gets a pointer to the sub-container at the specified id. Changes to the pointed container are reflected in the stored sub-container.

Parameters
[in]idThe ID of the requested sub-container ID.
Returns
A pointer to the sub-container, or nullptr if it does not exist. The container owns the pointed sub-container.

§ GetContainerInstance() [2/2]

const BaseContainer* GetContainerInstance ( Int32  id) const

Gets a read-only pointer to the sub-container with the specified id.

Since
R17.032
Parameters
[in]idThe ID of the requested sub-container ID.
Returns
A pointer to the sub-container, or nullptr if it does not exist. The container owns the pointed sub-container.

§ GetLink()

BaseList2D* GetLink ( Int32  id,
const BaseDocument doc,
Int32  instanceof = 0 
) const

Gets a linked baselist node at the specified id. Equivalent to BaseLink::GetLink().
If instanceof is specified, nullptr is returned if the node is not of this type.

Parameters
[in]idThe ID of the requested value.
[in]docThe document to evaluate the link in. The caller owns the pointed document.
[in]instanceofSet this to a node type to only return the link if it is of this type.
Returns
The linked object, or nullptr if the link is broken. The document owns the pointed linked baselist.

§ GetObjectLink()

BaseObject* GetObjectLink ( Int32  id,
const BaseDocument doc 
) const

Gets a linked object at the specified id.

Parameters
[in]idThe ID of the requested object link.
[in]docThe document to evaluate the object link in. The caller owns the pointed document.
Returns
The linked object, or nullptr if the link is broken. The document owns the pointed linked object.

§ GetMaterialLink()

BaseMaterial* GetMaterialLink ( Int32  id,
const BaseDocument doc 
) const

Gets a linked material at the specified id.

Parameters
[in]idThe ID of the requested link.
[in]docThe document to evaluate the link in. The caller owns the pointed document.
Returns
The linked material, or nullptr if the link is broken. The document owns the pointed linked material.

§ GetBaseLink()

BaseLink* GetBaseLink ( Int32  id) const

Gets the BaseLink at the specified id.

Parameters
[in]idThe ID of the requested link.
Returns
The link, or nullptr if there is no link stored. The container owns the pointed link.

§ GetCustomDataType()

const CustomDataType* GetCustomDataType ( Int32  id,
Int32  datatype 
) const

Gets the CustomDataType value at the specified id.

Parameters
[in]idThe ID of the requested custom datatype.
[in]datatypeThe datatype type ID.
Returns
The custom datatype, or nullptr if it does not exist or the wrong datatype was specified. The container owns the pointed custom datatype.

§ GetType()

Int32 GetType ( Int32  id) const

Gets the type of the element at the specified id.

Parameters
[in]idThe ID of the element.
Returns
The type of the element: DA_TYPES

§ SetBool()

void SetBool ( Int32  id,
Bool  b 
)

Sets the Bool value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]bThe new or inserted value.

§ SetInt32()

void SetInt32 ( Int32  id,
Int32  l 
)

Sets the Int32 value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]lThe new or inserted value.

§ SetUInt32()

void SetUInt32 ( Int32  id,
UInt32  l 
)

Sets the UInt32 value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]lThe new or inserted value.

§ SetInt64()

void SetInt64 ( Int32  id,
Int64  l 
)

Sets the Int64 value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]lThe new or inserted value.

§ SetUInt64()

void SetUInt64 ( Int32  id,
UInt64  l 
)

Sets the UInt64 value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]lThe new or inserted value.

§ SetFloat()

void SetFloat ( Int32  id,
Float  r 
)

Sets the Float value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]rThe new or inserted value.

§ SetVoid()

void SetVoid ( Int32  id,
void *  v 
)

Sets the void* value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]vThe new or inserted value.

§ SetMemory()

void SetMemory ( Int32  id,
void *  mem,
Int  count 
)

Sets the memory block at the specified id to mem, or inserts it if it did not exist.

Parameters
[in]idThe ID of the value to set.
[in]memThe memory buffer. The container takes the ownership over the memory buffer.
[in]countThe number of bytes in mem.

§ SetVector()

void SetVector ( Int32  id,
const Vector v 
)

Sets the Vector value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]vThe new or inserted value.

§ SetMatrix()

void SetMatrix ( Int32  id,
const Matrix m 
)

Sets the Matrix value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]mThe new or inserted value.

§ SetString()

void SetString ( Int32  id,
const String s 
)

Sets the String value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]sThe new or inserted value.

§ SetUuid()

void SetUuid ( Int32  id,
const C4DUuid u 
)

Sets the C4DUuid value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]uThe new or inserted value.

§ SetFilename()

void SetFilename ( Int32  id,
const Filename f 
)

Sets the Filename value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]fThe new or inserted value.

§ SetTime()

void SetTime ( Int32  id,
const BaseTime b 
)

Sets the BaseTime value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]bThe new or inserted value.

§ SetContainer()

void SetContainer ( Int32  id,
const BaseContainer s 
)

Sets the sub-container value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]sThe new or inserted value.

§ SetLink()

void SetLink ( Int32  id,
C4DAtomGoal link 
)

Sets the link value at the specified id, or inserts it if it does not exist.

Parameters
[in]idThe ID of the value to set.
[in]linkThe new or inserted value.

§ MergeContainer()

void MergeContainer ( const BaseContainer src)

Stores the values from src in the container, overwriting any elements with the same IDs and keeping the rest.

Parameters
[in]srcThe source container to merge.

§ GetParameter()

Bool GetParameter ( const DescID id,
GeData t_data 
) const

Retrieves the GeData for the specified parameter description id.

Parameters
[in]idThe ID of the requested data.
[out]t_dataAssigned the retrieved data.
Returns
true if successful, otherwise false.

§ SetParameter()

Bool SetParameter ( const DescID id,
const GeData t_data 
)

Sets the GeData for the specified parameter description id.

Parameters
[in]idThe ID of the parameter to set.
[in]t_dataThe data to set or insert.

§ Sort()

void Sort ( )

Sorts the container entries by ID.

Member Data Documentation

§ dummy1

void* dummy1
private

§ dummy2

Int dummy2
private

§ dummy3

Int32 dummy3
private

§ dummy4

Int32 dummy4
private

§ dummy5

Int32 dummy5
private