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 ()

Assign/Clone/Copy
const BaseContainer &	operator= (const BaseContainer &n)
BaseContainer *	GetClone (COPYFLAGS flags, AliasTrans *trans) const
Bool	CopyTo (BaseContainer *dst, COPYFLAGS flags, AliasTrans *trans) const

Flush All
void	FlushAll ()

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 GeData *	GetDataPointer (Int32 id) const
void	GetDataPointers (const Int32 *ids, Int32 cnt, const GeData **data) const

Data
GeData *	GetIndexData (Int32 index) const
GeData *	InsData (Int32 id, const GeData &n)
GeData *	InsDataAfter (Int32 id, const GeData &n, GeData *last)
GeData *	SetData (Int32 id, const GeData &n)
const GeData &	GetData (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 maxon::String &preset=maxon::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
BaseContainer *	GetContainerInstance (Int32 id)
const BaseContainer *	GetContainerInstance (Int32 id) const
BaseList2D *	GetLink (Int32 id, const BaseDocument *doc, Int32 instanceof=0) const
BaseObject *	GetObjectLink (Int32 id, const BaseDocument *doc) const
BaseMaterial *	GetMaterialLink (Int32 id, const BaseDocument *doc) const
BaseLink *	GetBaseLink (Int32 id) const
const CustomDataType *	GetCustomDataType (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 maxon::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]

BaseContainer

(

)

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]

id

The 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]

n

The source container.

~BaseContainer()

~BaseContainer

(

)

Destructor.

Member Function Documentation

operator=()

const BaseContainer& operator=

(

const BaseContainer &

n

)

Assignment operator. Copies all values from the source container.

Parameters

[in]

n

The 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]	flags	The flags for the clone: COPYFLAGS
[in]	trans	An 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]	dst	The destination container. The caller owns the pointed container.
[in]	flags	The flags for the clone: COPYFLAGS
[in]	trans	An alias translator for the operation. Can be nullptr. The caller owns the pointed alias translator.

Returns

true if successful, otherwise false.

FlushAll()

void FlushAll

(

)

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_id

The 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]

id

The 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]

i

The 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]	id	The ID of the value.
[out]	ppData	Assigned 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]

index

The 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]

id

The 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]	ids	Assigned a pointer to the array of data IDs. The container owns the pointed array.
[in]	cnt	The number of array elements.
[out]	data	Assigned 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]

index

The 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]	id	The ID to insert at.
[in]	n	The 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]	id	The ID to insert at.
[in]	n	The data to insert.
[in]	last	The 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]	id	The ID of the element to set.
[in]	n	The 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]

id

The 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.

Note

IDs have to be in the same order.

Parameters

[in]

d

The 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]

d

The 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[out]	count	Assigned the number of bytes in the memory buffer returned.
[in]	preset	Returned 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]	id	The ID of the requested value.
[out]	count	Assigned the number of bytes in the memory buffer returned.
[in]	preset	Returned if the value is not available.

Returns

The memory buffer, or preset if it does not exist. The container owns the pointed memory block.

GetVector()

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

Gets the Vector value at the specified id.

Parameters

[in]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned if the value is not available.

Returns

The value.

GetString()

String GetString	(	Int32	id,
		const maxon::String &	preset = maxon::String()
	)		const

Gets the String value at the specified id.

Parameters

[in]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]	id	The ID of the requested value.
[in]	preset	Returned 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]

id

The 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]

id

The 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]

id

The 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]	id	The ID of the requested value.
[in]	doc	The document to evaluate the link in. The caller owns the pointed document.
[in]	instanceof	Set 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]	id	The ID of the requested object link.
[in]	doc	The 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]	id	The ID of the requested link.
[in]	doc	The 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]

id

The 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]	id	The ID of the requested custom datatype.
[in]	datatype	The 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]

id

The 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]	id	The ID of the value to set.
[in]	b	The 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]	id	The ID of the value to set.
[in]	l	The 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]	id	The ID of the value to set.
[in]	l	The 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]	id	The ID of the value to set.
[in]	l	The 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]	id	The ID of the value to set.
[in]	l	The 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]	id	The ID of the value to set.
[in]	r	The 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]	id	The ID of the value to set.
[in]	v	The 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]	id	The ID of the value to set.
[in]	mem	The memory buffer. The container takes the ownership over the memory buffer.
[in]	count	The 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]	id	The ID of the value to set.
[in]	v	The 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]	id	The ID of the value to set.
[in]	m	The new or inserted value.

SetString()

void SetString	(	Int32	id,
		const maxon::String &	s
	)

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

Parameters

[in]	id	The ID of the value to set.
[in]	s	The 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]	id	The ID of the value to set.
[in]	u	The 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]	id	The ID of the value to set.
[in]	f	The 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]	id	The ID of the value to set.
[in]	b	The 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]	id	The ID of the value to set.
[in]	s	The 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]	id	The ID of the value to set.
[in]	link	The 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]

src

The 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]	id	The ID of the requested data.
[out]	t_data	Assigned 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]	id	The ID of the parameter to set.
[in]	t_data	The data to set or insert.

Sort()

void Sort

(

)

Sorts the container entries by ID except ID 1. Remove all value except string and subcontainer.

Warning

This function is used for menu and should not be used to sort the basecontainer.

Member Data Documentation

dummy1

void* dummy1

private

dummy2

Int dummy2

private

dummy3

Int32 dummy3

private

dummy4

Int32 dummy4

private

dummy5

Int32 dummy5

private