c4d.BaseContainer

class c4d.BaseContainer
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.
There is no guarantee that a value is there in the container.
Keep in mind that there is no guarantee for a value to be in the container.
Use default values whenever possible when accessing the values.
Maybe your plugin won’t be able to change some values, but it will work anyway.
It is recommended that you use the available containers to store your own values as well.
That way they will be automatically saved.
However, if you want to store values in the top level of for example an object container, you’ll have to use a unique id.
You can use a plugin id from Plugin Cafe for this.
A good way is to store a sub-container with this id. Inside this sub-container you can use whatever ids you want.
Once you’ve set a container value 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.

Methods Signatures

Magic Methods

BaseContainer.__init__()

Initializes a new container.

BaseContainer.__iter__()

The BaseContainer is iterable so just use it like in the following example:

BaseContainer.__getitem__()

Returns a value with the specified ID.

BaseContainer.__setitem__()

Automatically redirect the value to the corresponding Set* method.

BaseContainer.__ne__()

Check if the compared containers don’t have the same ID, don’t have the same values, and all values are not equal.

BaseContainer.__eq__()

Check if the compared containers have the same ID, have the same values, and all values are equal.

BaseContainer.__len__()

Calculates the number of data elements inside the container.

Deprecated

BaseContainer.GetLLong()

Deprecated since version R15: Use GetInt64() instead.

BaseContainer.GetLong()

Deprecated since version R15: Use GetInt32() instead.

BaseContainer.GetReal()

Deprecated since version R15: Use GetFloat() instead.

BaseContainer.SetLLong()

Deprecated since version R15: Use SetInt64() instead.

BaseContainer.SetLong()

Deprecated since version R15: Use SetInt32() instead.

BaseContainer.SetReal()

Deprecated since version R15: Use SetFloat() instead.

Uncategorized

BaseContainer.GetClone()

Returns a copy of the container including all values.

BaseContainer.CopyTo()

Copies all values to dst.

BaseContainer.FlushAll()

Clears all values in the container.

BaseContainer.GetId()

Returns the ID of the container.

BaseContainer.SetId()

Sets the ID of the container.

BaseContainer.GetDirty()

Returns the dirty count.

BaseContainer.RemoveData()

Removes the first data item with the specified ID.

BaseContainer.RemoveIndex()

Removes the data item at the specified index i.

BaseContainer.FindIndex()

Returns the index for the value with the specified ID and its assigned data, or -1 if no such value exists.

BaseContainer.GetIndexId()

Returns the ID of the element at the specified index, or NOTOK if it doesn’t exist.

BaseContainer.GetType()

Returns the type of a container element by ID.

BaseContainer.InsData()

Inserts an arbitrary data at the specified id.

BaseContainer.InsDataAfter()

Inserts an arbitrary data at the specified id after last.

BaseContainer.SetData()

Sets an arbitrary data value at the specified ID.

BaseContainer.GetData()

Returns the data for an element by ID.

BaseContainer.GetDataPointer()

Retrieves a pointer to directly access the data.

BaseContainer.GetBool()

Returns a bool value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetInt32()

Returns a int value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetInt64()

Returns a long value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetFloat()

Returns a float value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetVector()

Returns a Vector value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetMatrix()

Returns a Matrix value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetString()

Returns a string value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetFilename()

Returns a string value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetUuid()

Returns a uuid value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetTime()

Returns a BaseTime value with the specified ID, or preset if it doesn’t exist.

BaseContainer.GetContainer()

Returns a copy of the sub-container with the specified ID, or an empty container if it doesn’t exist.

BaseContainer.GetContainerInstance()

Returns the sub-container with the specified ID, or None if it doesn’t exist.

BaseContainer.GetLink()

Returns a linked object, evaluated in the attached document.

BaseContainer.GetObjectLink()

Returns a linked base object, evaluated in the attached document.

BaseContainer.GetMaterialLink()

Returns a linked material object, evaluated in the attached document.

BaseContainer.GetCustomDataType()

Returns a copy of the custom data type or None if it doesn’t exist.

BaseContainer.GetVoid()

Gets the void* value at the specified id.

BaseContainer.SetBool()

Sets a bool value and changes the data type accordingly.

BaseContainer.SetInt32()

Sets an int value and changes the data type accordingly.

BaseContainer.SetInt64()

Sets a long value and changes the data type accordingly.

BaseContainer.SetFloat()

Sets a float value and changes the data type accordingly.

BaseContainer.SetVector()

Sets a Vector value and changes the data type accordingly.

BaseContainer.SetMatrix()

Sets a Matrix value and changes the data type accordingly.

BaseContainer.SetString()

Sets a string value and changes the data type accordingly.

BaseContainer.SetFilename()

Sets a new string value with the specified ID to s as a filepath, or inserts it if it didn’t exist.

BaseContainer.SetUuid()

Sets a uuid value and changes the data type accordingly.

BaseContainer.SetTime()

Sets a BaseTime value and changes the data type accordingly.

BaseContainer.SetContainer()

Sets a BaseContainer value and changes the data type accordingly.

BaseContainer.SetLink()

Stores a link to an atom object with the specified ID.

BaseContainer.SetVoid()

Stores a PyCObject to an void* object with the specified ID.

BaseContainer.GetIndexData()

Retrieves the data for the element at index.

BaseContainer.SetIndexData()

Sets the data for the element at index.

BaseContainer.IsInstance()

Checks if the container is an instance.

BaseContainer.MergeContainer()

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

BaseContainer.Sort()

Sorts the container entries by ID.

Methods Documentation

BaseContainer.__init__(self, n=NOTOK)

Initializes a new container.

Parameters

n (Optional[Union[c4d.BaseContainer, int]]) – Use int if you just want to set the ID of the container. Pass a container if you want to clone it, or None to use a standard empty container.

BaseContainer.__iter__(self)

The BaseContainer is iterable so just use it like in the following example:

>>> bc = c4d.BaseContainer()
>>> bc[0] = "foo"
>>> bc[37] = "bar"
>>> bc[42] = False

>>> for index, value in bc:
...     print(f"id: {index}, val: {value}")
id: 0, val: foo
id: 37, val: bar
id: 42, val: 0
BaseContainer.__getitem__(self, key)

Returns a value with the specified ID.

Parameters

key (int) – Index of the value.

Return type

Any

Returns

Any value.

BaseContainer.__setitem__(self, key, value)
Automatically redirect the value to the corresponding Set* method.
Its recommended to use the original Set* method to avoid type problems.

Warning

This method can replace types.
Please check the types before when a special key is associated with a special type.

To delete a key, call del(bc[i]) or RemoveData().

Parameters
  • key (int) – Index of the value.

  • value (any) – It depends on the type which Set* method is internally called.

BaseContainer.__ne__(self, other)

Check if the compared containers don’t have the same ID, don’t have the same values, and all values are not equal.

Parameters

other (c4d.BaseContainer) – Returns True if the compared containers are equal.

BaseContainer.__eq__(self, other)

Check if the compared containers have the same ID, have the same values, and all values are equal.

Parameters

other (c4d.BaseContainer) – Returns True if the compared containers are equal.

BaseContainer.__len__(self)

Calculates the number of data elements inside the container.

Return type

int

Returns

The number of data elements.

BaseContainer.GetLLong(self, id, preset=0)

Deprecated since version R15: Use GetInt64() instead.

Returns a long value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (int) – Returned if the value is not available.

Return type

int

Returns

The value.

BaseContainer.GetLong(self, id, preset=0)

Deprecated since version R15: Use GetInt32() instead.

Returns a int value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (int) – Returned if the value is not available.

Return type

int

Returns

The value.

BaseContainer.GetReal(self, id, preset=0.0)

Deprecated since version R15: Use GetFloat() instead.

Returns a float value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (float) – Returned if the value is not available.

Return type

float

Returns

The value.

BaseContainer.SetLLong(self, id, l)

Deprecated since version R15: Use SetInt64() instead.

Sets a long value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • l (int) – The new value.

BaseContainer.SetLong(self, id, l)

Deprecated since version R15: Use SetInt32() instead.

Sets an int value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • l (int) – The new value.

BaseContainer.SetReal(self, id, v)

Deprecated since version R15: Use SetFloat() instead.

Sets a float value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • l (int) – The new value.

BaseContainer.GetClone(self, flags, trans=None)

Returns a copy of the container including all values.

Parameters
  • flags (int) –

    Flags:

    COPYFLAGS_NONE

    None.

    COPYFLAGS_PRIVATE_CONTAINER_COPY_DIRTY

    Private.

    COPYFLAGS_PRIVATE_CONTAINER_COPY_IDENTICAL

    Private.

  • trans (Optional[c4d.AliasTrans]) –

    New in version R17.032.

    An optional alias translator for the operation.

Return type

c4d.BaseContainer

Returns

The cloned container.

BaseContainer.CopyTo(self, dst, flags, trans=None)

Copies all values to dst.

Parameters
  • dst (c4d.BaseContainer) – The destination container.

  • flags (int) –

    Flags:

    COPYFLAGS_NONE

    None.

    COPYFLAGS_PRIVATE_CONTAINER_COPY_DIRTY

    Private.

    COPYFLAGS_PRIVATE_CONTAINER_COPY_IDENTICAL

    Private.

  • trans (Optional[c4d.AliasTrans]) –

    New in version R17.032.

    An optional alias translator for the operation.

BaseContainer.FlushAll(self)
Clears all values in the container.
The container ID is not changed.
BaseContainer.GetId(self)

Returns the ID of the container.

Return type

int

Returns

The container ID.

BaseContainer.SetId(self, id)

Sets the ID of the container.

Parameters

id (int) – The container ID.

BaseContainer.GetDirty(self)
Returns the dirty count.
Can be used to check if the container has changed.
Return type

int

Returns

Dirty counter. It is incremented when the container changes.

BaseContainer.RemoveData(self, id)

Removes the first data item with the specified ID.

Parameters

id (int) – The container ID.

Return type

bool

Returns

True if any value was removed, otherwise False.

BaseContainer.RemoveIndex(self, i)

Removes the data item at the specified index i.

Parameters

i (int) – The index of the value to be removed.

Return type

bool

Returns

True if any value was removed, otherwise False.

BaseContainer.FindIndex(self, i)

Returns the index for the value with the specified ID and its assigned data, or -1 if no such value exists.

Parameters

i (int) – The ID of the value.

Return type

Dict[index: int, ppData: Any]

Returns

The index of the value, or -1 if not found and its assigned data if found.

BaseContainer.GetIndexId(self, index)
Returns the ID of the element at the specified index, or NOTOK if it doesn’t exist.
Used to browse through the container.
Parameters

index (int) – The index of the value.

Return type

bool

Returns

The ID of the value, or NOTOK.

BaseContainer.GetType(self, id)

Returns the type of a container element by ID.

Parameters

id (int) – The ID of the element.

Return type

int

Returns

The type:

DA_NIL

No value.

DA_VOID

PyCObject

DA_LONG

Integer.

DA_REAL

Float.

DA_TIME

BaseTime.

DA_VECTOR

Vector.

DA_MATRIX

Matrix.

DA_LLONG

Integer.

DA_STRING

String.

DA_FILENAME

String.

DA_CONTAINER

BaseContainer.

DA_ALIASLINK

BaseList2D.

DA_MARKER

Not used.

DA_MISSINGPLUG

Denotes a missing datatype plugin.

DA_UUID

New in version R17.048: UUID.

DA_TRISTATE

New in version R20: No single value.

DA_CUSTOMDATATYPE

Datatypes higher than this value are custom.

BaseContainer.InsData(self, id, n)

Inserts an arbitrary data at the specified id.

Warning

This function does not check if the ID already exists in the container!

Parameters
  • id (int) – The ID to insert at.

  • n (any) – The data to insert.

Return type

Any

Returns

The inserted data.

BaseContainer.InsDataAfter(self, id, n, last)

Inserts an arbitrary data at the specified id after last.

Warning

This function does not check if the ID already exists in the container!

Parameters
  • id (int) – The ID to insert at.

  • n (any) – The data to insert.

  • last (any) – The data to insert after.

Return type

Any

Returns

The inserted data.

BaseContainer.SetData(self, id, n)
Sets an arbitrary data value at the specified ID.
If a value exists under the same ID, its content will be changed.
Parameters
  • id (int) – The ID of the element to set.

  • n (any) – The data value to set.

BaseContainer.GetData(self, id)

Returns the data for an element by ID.

Parameters

id (int) – The ID of the element.

Return type

Optional[Any]

Returns

The data or None if it wasn’t found.

BaseContainer.GetDataPointer(self, id)

Retrieves a pointer to directly access the data.

New in version R17.053.

bc = c4d.BaseContainer()
bc[1000] = "hello"
bc[2000] = "world"

# Print content
print("Original:")
for dataid, data in bc:
    print(data)

dataptr = bc.GetDataPointer(1000)
bc.InsDataAfter(3000, "beautiful", dataptr)

# Print content
print("Changed:")
for dataid, data in bc:
    print(data)
print(" ")
Parameters

id (int) – The ID of the element.

Return type

PyCObject

Returns

A pointer to the data.

BaseContainer.GetBool(self, id, preset=False)

Returns a bool value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (bool) – Returned if the value is not available.

Return type

bool

Returns

The value.

BaseContainer.GetInt32(self, id, preset=0)

Returns a int value with the specified ID, or preset if it doesn’t exist.

New in version R15.037.

Parameters
  • id (int) – The ID of the requested value.

  • preset (int) – Returned if the value is not available.

Return type

int

Returns

The value.

BaseContainer.GetInt64(self, id, preset=0)

Returns a long value with the specified ID, or preset if it doesn’t exist.

New in version R15.037.

Parameters
  • id (int) – The ID of the requested value.

  • preset (int) – Returned if the value is not available.

Return type

int

Returns

The value.

BaseContainer.GetFloat(self, id, preset=0.0)

Returns a float value with the specified ID, or preset if it doesn’t exist.

New in version R15.037.

Parameters
  • id (int) – The ID of the requested value.

  • preset (float) – Returned if the value is not available.

Return type

float

Returns

The value.

BaseContainer.GetVector(self, id, preset=Vector())

Returns a Vector value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (c4d.Vector) – Returned if the value is not available.

Return type

c4d.Vector

Returns

The value.

BaseContainer.GetMatrix(self, id, preset=Matrix())

Returns a Matrix value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (c4d.Matrix) – Returned if the value is not available.

Return type

c4d.Matrix

Returns

The value.

BaseContainer.GetString(self, id, preset='')

Returns a string value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (str) – Returned if the value is not available.

Return type

str

Returns

The value.

BaseContainer.GetFilename(self, id, preset='')

Returns a string value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (str) – Returned if the value is not available.

Return type

str

Returns

The value.

BaseContainer.GetUuid(self, id, preset)

Returns a uuid value with the specified ID, or preset if it doesn’t exist.

New in version R16.021.

Parameters
  • id (int) – The ID of the requested value.

  • preset – Returned if the value is not available.

Return type

UUID

Returns

The value.

BaseContainer.GetTime(self, id, preset=BaseTime())

Returns a BaseTime value with the specified ID, or preset if it doesn’t exist.

Parameters
  • id (int) – The ID of the requested value.

  • preset (c4d.BaseTime) – Returned if the value is not available.

Return type

c4d.BaseTime

Returns

The value.

BaseContainer.GetContainer(self, id)

Returns a copy of the sub-container with the specified ID, or an empty container if it doesn’t exist.

Parameters

id (int) – The ID of the requested sub-container.

Return type

c4d.BaseContainer

Returns

The Sub-container.

BaseContainer.GetContainerInstance(self, id)
Returns the sub-container with the specified ID, or None if it doesn’t exist.
Changes to the container are reflected in the stored sub-container.
Parameters

id (int) – The ID of the requested sub-container.

Return type

Optional[c4d.BaseContainer]

Returns

The sub-container, or None.

Returns a linked object, evaluated in the attached document.

Note

If instanceof is specified, None is returned if the object is not of this type.

Parameters
  • id (int) – The ID of the requested sub-container.

  • doc (Optional[c4d.documents.BaseDocument]) – The document to evalulate the link in or None.

  • isinstanceof (int) – Set this to a node type to only return the link if it is of this type.

Return type

Optional[c4d.BaseList2D]

Returns

The linked object, or None if the link is broken.

Returns a linked base object, evaluated in the attached document.

Note

Returns None if the link doesn’t point to a base object.

Parameters
  • id (int) – The ID of the requested sub-container.

  • doc (Optional[c4d.documents.BaseDocument]) – The document to evalulate the link in.

Return type

Optional[c4d.BaseObject]

Returns

The linked base object, or None if the link is broken.

Returns a linked material object, evaluated in the attached document.

Note

Returns None if the link doesn’t point to a base object.

Parameters
  • id (int) – The ID of the requested sub-container.

  • doc (Optional[c4d.documents.BaseDocument]) – The document to evalulate the link in.

Return type

Optional[c4d.BaseMaterial]

Returns

The linked material object, or None if the link is broken.

BaseContainer.GetCustomDataType(self, id)

Returns a copy of the custom data type or None if it doesn’t exist.

Parameters

id (int) – The ID of the requested sub-container.

Returns

The custom data type.

Return type

Optional[object]

BaseContainer.GetVoid(self, id)

Gets the void* value at the specified id.

Parameters

id (int) – The ID of the requested void object.

Return type

PyCObject

Returns

The PyCObject representing the void object.

BaseContainer.SetBool(self, id, b)

Sets a bool value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • b (bool) – The new value.

BaseContainer.SetInt32(self, id, l)

Sets an int value and changes the data type accordingly.

New in version R15.037.

Parameters
  • id (int) – The ID of the value to set.

  • l (int) – The new value.

BaseContainer.SetInt64(self, id, l)

Sets a long value and changes the data type accordingly.

New in version R15.037.

Parameters
  • id (int) – The ID of the value to set.

  • l (int) – The new value.

BaseContainer.SetFloat(self, id, v)

Sets a float value and changes the data type accordingly.

New in version R15.037.

Parameters
  • id (int) – The ID of the value to set.

  • l (int) – The new value.

BaseContainer.SetVector(self, id, v)

Sets a Vector value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • v (c4d.Vector) – The new value.

BaseContainer.SetMatrix(self, id, m)

Sets a Matrix value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • m (c4d.Matrix) – The new value.

BaseContainer.SetString(self, id, s)

Sets a string value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • s (str) – The new value.

BaseContainer.SetFilename(self, id, f)

Sets a new string value with the specified ID to s as a filepath, or inserts it if it didn’t exist.

Parameters
  • id (int) – The ID of the value to set.

  • f (str) – The new value.

BaseContainer.SetUuid(self, id, u)

Sets a uuid value and changes the data type accordingly.

New in version R16.021.

Parameters
  • id (int) – The ID of the value to set.

  • u – The new value.

BaseContainer.SetTime(self, id, b)

Sets a BaseTime value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • b (c4d.BaseTime) – The new value.

BaseContainer.SetContainer(self, id, s)

Sets a BaseContainer value and changes the data type accordingly.

Parameters
  • id (int) – The ID of the value to set.

  • s (c4d.BaseContainer) – The sub-container

Stores a link to an atom object with the specified ID.

Parameters
  • id (int) – The ID of the value to set.

  • link (c4d.C4DAtom) – The link to store.

BaseContainer.SetVoid(self, id, v)

Stores a PyCObject to an void* object with the specified ID.

Parameters
  • id (int) – The ID of the requested void object.

  • v (PyCObject) – The void* as a PyCObject to store.

BaseContainer.GetIndexData(self, index)

Retrieves the data for the element at index.

New in version R16.038.

Parameters

index (int) – The index of the element.

Return type

Optional[Any]

Returns

The data, or None if no data was found.

BaseContainer.SetIndexData(self, index, data)

Sets the data for the element at index.

New in version R16.038.

Parameters
  • index (int) – The index of the element.

  • data (any) – The data for the element.

Return type

bool

Returns

True if the data was set, otherwise False.

BaseContainer.IsInstance(self)

Checks if the container is an instance.

Return type

bool

Returns

True if the container is an instance, otherwise False.

BaseContainer.MergeContainer(self, src)

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

Parameters

src (c4d.BaseContainer) – The source container.

BaseContainer.Sort(self)

Sorts the container entries by ID.