About

A ColorSwatchData object can manage multiple color groups. These color groups can be loaded globally from Cinema 4D, a BaseDocument or a preset and saved back to these sources. Local color groups and global color groups are stored separately. The class is defined in the lib_colorchooser.h header file.

// This example loops through all colors of all color groups of the given BaseDocument.
// For each selected color a new material is created.
// load document color swatches
ColorSwatchData* const colorSwatchData = ColorSwatchData::Alloc(doc, false);
if (colorSwatchData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// AutoFree takes ownership
freeData.Assign(colorSwatchData);
// loop through groups
const Int groupCount = colorSwatchData->GetGroupCount();
for (Int i = 0; i < groupCount; ++i)
{
ColorSwatchGroup* group = colorSwatchData->GetGroupAtIndex(i);
if (group)
{
// loop through colors
const Int colorCount = group->GetColorCount();
for (Int c = 0; c < colorCount; ++c)
{
Bool selected = false;
// get color and check if it is selected
if (group->GetColor(c, color, &selected) && selected)
{
// create new material
Material* const mat = Material::Alloc();
if (mat == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// use color
const Vector rgb(color.r, color.g, color.b);
doc->InsertMaterial(mat);
}
}
}
}

Allocation/Deallocation

ColorSwatchData instances are created with the usual tools:

// This example allocates a new ColorSwatchData object.
// During allocation the color groups of the given BaseDocument are automatically loaded.
if (data == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Int groupCount = data->GetGroupCount();
ApplicationOutput("The document contains " + String::IntToString(groupCount) + " color groups");

Document Colors

Color groups can be stored in a BaseDocument:

// This example loads a Cinema 4D scene file.
// The color swatches of this file are loaded into the given ColorSwatchData object.
// The merged colors are saved back to the original document.
// load colors of the original
if (!colorSwatchData->Load(doc))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// select the scene file
Filename sceneFile;
// open a dialog to select a file
if (!sceneFile.FileSelect(FILESELECTTYPE::SCENES, FILESELECT::LOAD, "Select File"_s))
return maxon::OK;
// load the scene file
BaseDocument* loadedDoc = LoadDocument(sceneFile, SCENEFILTER::NONE, nullptr);
if (loadedDoc == nullptr)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(sceneFile, MAXONCONVERTMODE::NONE), "Could not load document."_s);
// merge the scene file colors
colorSwatchData->Load(loadedDoc, true);
// store merged colors back into the BaseDocument
colorSwatchData->Save(doc);
BaseDocument::Free(loadedDoc);

Presets

Color swatches can also be stored in the preset library:

To make work with presets easier these utility functions exist:

// This example checks if a color swatches preset with the given name already exists.
// If not, the preset is created.
const String presetName("myColorPreset");
// check if preset already exists
{
// construct url
url += presetName;
// save preset
if (!colorSwatchData->SavePreset(url, "User", "This is my preset"))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
}

Color Groups

The color swatches stored in a ColorSwatchData are stored in groups. These groups can either be stored with the document (SWATCH_CATEGORY::DOCUMENT) or with Cinema 4D itself (SWATCH_CATEGORY::GLOBAL).

// This example adds a new group to the given ColorSwatchData.
// Then the name of each group is printed.
colorSwatchData->AddGroup(SWATCH_CATEGORY::DOCUMENT, "New Group");
const Int groupCount = colorSwatchData->GetGroupCount(SWATCH_CATEGORY::DOCUMENT);
for (Int i = 0; i < groupCount; ++i)
{
const ColorSwatchGroup* const group = colorSwatchData->GetGroupAtIndex(i, SWATCH_CATEGORY::DOCUMENT);
if (group != nullptr)
{
ApplicationOutput("Group Name: " + group->GetName());
}
}

Further utility functions are:

Further Reading