BaseContainer Manual

Table of Contents

About

A BaseContainer is a collection of individual values. Each value has its own ID and type. A BaseContainer 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 containers, so this class is an essential part of the SDK. Containers can store any GeData type, including custom data types. It is recommended to use the available containers to store values in custom NodeData based plugins.

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 BaseContainer::GetBool()) whenever possible, instead of the low-level BaseContainer::GetData(). See Access.
Once a container value has been set using one type one 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.
Note
To browse through all elements of a BaseContainer use the class BrowseContainer.

Access

Every BaseList2D based object of the Cinema 4D API has a BaseContainer that stores its data. This BaseContainer can be accessed with:

See BaseList2D Manual.

Note
Object parameters should be edited with C4DAtom::GetParameter() / C4DAtom::SetParameter(). Not all parameters of an object may be stored in the BaseContainer.
// This example accesses the BaseContainer storing the render settings.
// The BaseContainer is needed as an argument of RenderDocument().
RenderData* const rdata = doc->GetActiveRenderData();
if (rdata == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const BaseContainer renderSettings = rdata->GetData();
AutoAlloc<BaseBitmap> bitmap;
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// prepare target bitmap
const Int32 width = renderSettings.GetInt32(RDATA_XRES, 1280);
const Int32 height = renderSettings.GetInt32(RDATA_YRES, 720);
const IMAGERESULT imageRes = bitmap->Init(width, height);
if (imageRes != IMAGERESULT::OK)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// render the image
const RENDERFLAGS flags = RENDERFLAGS::NODOCUMENTCLONE;
const RENDERRESULT res = RenderDocument(doc, renderSettings, nullptr, nullptr, bitmap, flags, nullptr);
if (res != RENDERRESULT::OK)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// show the result in the Picture Viewer
ShowBitmap(bitmap);

BaseContainer elements are also often used as an argument in a function call.

Copy

The complete content of a BaseContainer object can be copied to another object:

It is also possible to copy a BaseContainer using the copy constructor.

// This example creates a BaseContainer copies in different ways:
BaseContainer original;
original.SetString(100, "foo"_s);
original.SetString(200, "bar"_s);
// CopyTo()
BaseContainer target;
target.SetString(300, "foobar"_s);
if (!original.CopyTo(&target, COPYFLAGS::NONE, nullptr))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ApplicationOutput(target.GetString(100));
ApplicationOutput(target.GetString(200));
ApplicationOutput(target.GetString(300)); // This value is now deleted.
// GetClone()
BaseContainer* clone = original.GetClone(COPYFLAGS::NONE, nullptr);
if (!clone)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
ApplicationOutput(clone->GetString(100));
ApplicationOutput(clone->GetString(200));
DeleteObj(clone);
// Copy Constructor
BaseContainer copy(original);
ApplicationOutput(copy.GetString(100));
ApplicationOutput(copy.GetString(200));
// Assignment
BaseContainer assignment = original;
ApplicationOutput(assignment.GetString(100));
ApplicationOutput(assignment.GetString(200));
Note
To merge containers see BaseContainer::MergeContainer() in chapter Functionality.

Data

ID

A BaseContainer can have an ID. This ID can be used to identify the container.

// This example shows how GetId() is used to identify the message sent to GeDialog::Message().
Int32 Message(const BaseContainer& msg, BaseContainer& result)
{
switch (msg.GetId())
{
case BFM_INTERACTSTART:
{
// interaction start; if the value is changed create an undo
_interactStart = true;
break;
}
case BFM_INTERACTEND:
{
// interaction end, if an undo was created, end it
if (_undoStarted)
{
BaseDocument* const doc = GetActiveDocument();
doc->EndUndo();
_undoStarted = false;
}
_interactStart = false;
break;
}
}
return SUPER::Message(msg, result);
}

Access

A BaseContainer stores its data using GeData objects. It is possible to access these GeData objects or the stored values directly using typed access functions. It is recommended to prefer the typed access functions.

A copy of a GeData element can be obtained with:

Note
The DescLevel::id property is used as the actual ID.
// This example stores some data in
// the BaseContainer using SetParameter().
BaseContainer bc;
bc.SetParameter(DescID(100), GeData("foobar"));
GeData data;
bc.GetParameter(DescID(100), data);
ApplicationOutput(data.GetString());

The GeData elements are also accessible via:

// This example stores some data in the
// BaseContainer using a GeData object.
BaseContainer bc;
bc.SetData(100, GeData("foobar"));
GeData data = bc.GetData(100);
ApplicationOutput(data.GetString());

For fast access read-only pointers to the GeData elements are accessible:

// This example accesses the data stored
// in the BaseContainer using data pointers.
BaseContainer bc;
bc.SetData(100, GeData("foo"));
bc.SetData(200, GeData("bar"));
const Int count = 2;
const GeData* data[count];
Int32 ids[] = { 100, 200 };
bc.GetDataPointers(ids, count, data);
if (data[0])
ApplicationOutput(data[0]->GetString());
if (data[1])
ApplicationOutput(data[1]->GetString());

A GeData element is also accessible via its index in the BaseContainer:

// This example accesses the data stored in the
// BaseContainer using the element index.
BaseContainer bc;
bc.SetData(100, GeData("foo"));
bc.SetData(200, GeData("bar"));
GeData* const first = bc.GetIndexData(0);
if (first)
ApplicationOutput(first->GetString());
GeData* const second = bc.GetIndexData(1);
if (second)
ApplicationOutput(second->GetString());

New GeData elements can be added to the BaseContainer:

// This example inserts some data into the
// BaseContainer after the first element.
BaseContainer bc;
bc.SetData(100, "foo");
bc.SetData(200, "foobar");
GeData* const data = bc.GetIndexData(0);
bc.InsDataAfter(150, String("bar"), data);

To access the values of primitive data types, these access functions are available:

See also Primitive Data Types Manual (Classic).

A BaseContainer can store a void pointer.

Note
This should not be used to store a reference to a C4DAtom based element; instead a BaseLink should be used.
// This example stores a void pointer
// in the BaseContainer object.
BaseContainer bc;
bc.SetVoid(100, &object);
// ...
SomeObject* const obj = static_cast<SomeObject*>(bc.GetVoid(100));

A BaseContainer can store raw memory:

// This example stores some raw memory
// in the BaseContainer object.
BaseContainer bc;
bc.SetMemory(100, memory, memSize);
// ...
Int count;
Char* const data = (Char*)bc.GetMemory(100, count, nullptr);
if (data)
{
String output;
output.SetCString(data, count);
ApplicationOutput(output);
}

A BaseContainer offers also access functions for mathematical data types:

See also Vector Manual (Classic) and Matrix Manual (Classic).

A BaseContainer offers further access functions for typical Cinema 4D data types:

See also String Manual (Classic) and Filename Manual.

See also BaseTime Manual.

A BaseContainer also offers special functions to store and handle BaseLink objects:

See also BaseLink Manual.

// store the current selection in the BaseContainer
BaseContainer bc;
bc.SetLink(100, doc->GetActiveMaterial());
bc.SetLink(200, doc->GetActiveObject());
bc.SetLink(300, doc->GetActiveTag());
// ...
// get the material
BaseMaterial* const mat = bc.GetMaterialLink(100, doc);
if (mat)
ApplicationOutput(mat->GetName());
// get the object
BaseObject* const obj = bc.GetObjectLink(200, doc);
if (obj)
ApplicationOutput(obj->GetName());
// get tag
BaseList2D* const link = bc.GetLink(300, doc);
if (link)
ApplicationOutput(link->GetName());

A BaseContainer object can also store further sub-containers:

// This example stores a sub-container
// in the BaseContainer object.
BaseContainer subcontainer;
subcontainer.SetString(100, "foobar"_s);
BaseContainer bc;
bc.SetContainer(100, subcontainer);
// ...
BaseContainer sub = bc.GetContainer(100);
ApplicationOutput(sub.GetString(100));

A BaseContainer can also store custom data types. To set the value of the custom data type a GeData object is needed.

// This example gets the current time and saves is as DateTimeData in the BaseContainer.
// Then the DateTimeData is received from that BaseContainer.
DateTime time;
GetDateTimeNow(time);
AutoAlloc<DateTimeData> date;
if (!date)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
date->SetDateTime(time);
GeData data;
data.SetCustomDataType(DATETIME_DATA, *date);
BaseContainer bc;
bc.SetData(100, data);
// ...
const CustomDataType* const customData = bc.GetCustomDataType(100, DATETIME_DATA);
const DateTimeData* const dateTimeData = static_cast<const DateTimeData*>(customData);
if (dateTimeData)
{
const DateTime dt = dateTimeData->GetDateTime();
String result;
result += String::IntToString(dt.year) + ":";
result += String::IntToString(dt.month) + ":";
result += String::IntToString(dt.day) + " - ";
result += String::IntToString(dt.hour) + ":";
result += String::IntToString(dt.minute) + ":";
result += String::IntToString(dt.second);
// print output
ApplicationOutput(result);
}

These functions can be used to limit the values of a Vector or Float value inside a BaseContaier:

Note
These functions simply apply ClampValue(), see also Mathematical Functions Manual (Classic).

Index

The elements stored within a BaseContainer are accessible through their index and their ID:

See also BaseContainer::GetIndexData() above. To loop through values see also BrowseContainer.

// This example loops through the values of the BaseContainer.
Int32 i = 0;
while (true)
{
const Int32 id = bc.GetIndexId(i++);
if (id == NOTOK)
break;
else
ApplicationOutput(bc.GetData(id).GetString());
}

Remove

Elements can be removed from a BaseContainer:

// This example removes some element from
// the BaseContainer object.
BaseContainer bc;
bc.SetData(100, "foo");
bc.SetData(200, "bar");
// remove data entry 100
if (bc.RemoveData(100))
{
GeData data = bc.GetData(100);
// check if data has no type (data is not set)
if (data.GetType() == DA_NIL)
ApplicationOutput("Data removed"_s);
}

Functionality

Several operations can be performed on a BaseContainer object.

// This example merges the content of two
// BaseContainer objects.
BaseContainer bc;
bc.SetData(100, "foo");
bc.SetData(200, "bar");
BaseContainer bc2;
bc2.SetData(100, "100");
bc2.SetData(300, "300");
bc.MergeContainer(bc2);
// this will result in the values
// 100: "100"
// 200: "bar"
// 300: "300"

Compare

Two BaseContainer are identical if they have the same ID, the same number of entries and if the entries are also identical.

Detect Changes

The dirty state of a BaseContainer changes incrementally when a value stored in the BaseContainer is changed.

// This example checks the dirty state after a value was added and changed.
BaseContainer bc;
bc.SetData(100, "foo");
UInt32 dirty = bc.GetDirty();
ApplicationOutput("Dirty State: " + String::UIntToString(dirty));
bc.SetData(100, "bar");
dirty = bc.GetDirty();
ApplicationOutput("Dirty State: " + String::UIntToString(dirty));

BrowseContainer

The BrowseContainer class can be used to browse through the values stored in a BaseContainer. See also Index.

// This example loops through all values of the given BaseContainer.
Int32 id;
GeData* dat = nullptr;
// init BrowseContainer
BrowseContainer browse(&bc);
// loop through the values
while (browse.GetNext(&id, &dat))
{
ApplicationOutput("id: " + String::IntToString(id));
// check if the current data stores a String
if (dat && dat->GetType() == DA_STRING)
{
ApplicationOutput("value: " + dat->GetString());
}
}

Disc I/O

A BaseContainer can be stored in a HyperFile.

// This example stores a BaseContainer in a HyperFile on disc.
AutoAlloc<HyperFile> hf;
if (!hf)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open HyperFile to write
if (hf->Open(123, filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
{
hf->WriteContainer(bc);
hf->Close();
}
else
{
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(filename, MAXONCONVERTMODE::NONE), "Could not open file."_s);
}
// This example reads a BaseContainer from a HyperFile on disc.
AutoAlloc<HyperFile> hf;
if (!hf)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open HyperFile to read
if (hf->Open(123, filename, FILEOPEN::READ, FILEDIALOG::ANY))
{
BaseContainer bc;
hf->ReadContainer(&bc, true);

See also HyperFile Manual on BaseContainer.

Further Reading