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);
}
}
}
}
Py_ssize_t i
Definition: abstract.h:645
Definition: ge_autoptr.h:155
void Assign(TYPE *p)
Definition: ge_autoptr.h:234
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
Definition: lib_colorchooser.h:406
Int GetGroupCount(SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT) const
ColorSwatchGroup * GetGroupAtIndex(Int index, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
static ColorSwatchData * Alloc(BaseDocument *doc=nullptr, Bool global=false)
Definition: lib_colorchooser.h:218
Bool GetColor(Int index, maxon::ColorA &color, Bool *selected=nullptr) const
Int GetColorCount() const
Definition: c4d_basematerial.h:241
static Material * Alloc()
Py_UNICODE c
Definition: unicodeobject.h:1200
maxon::Bool Bool
Definition: ge_sys_math.h:51
maxon::Int Int
Definition: ge_sys_math.h:60
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ConstDescID(...)
Definition: lib_description.h:594
@ MATERIAL_COLOR_COLOR
Definition: mmaterial.h:56
const char * doc
Definition: pyerrors.h:226
Represents a level within a DescID.
Definition: lib_description.h:298
A color consisting of three components R, G, B and an alpha.
Definition: col4.h:16
T r
Definition: col4.h:35
T g
Definition: col4.h:36
T b
Definition: col4.h:37

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");
static void Free(ColorSwatchData *&p)
static String IntToString(Int32 v)
Definition: c4d_string.h:497
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204

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);
BaseDocument * LoadDocument(const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr, const ProgressDelegate &progressDelegate=ProgressDelegate())
maxon::Url MaxonConvert(const Filename &fn, MAXONCONVERTMODE convertMode)
@ NONE
No check if file exists under case-sensitive drives.
Definition: c4d_basedocument.h:497
static void Free(BaseDocument *&bl)
Bool Save(BaseDocument *doc, Bool saveGlobalColors=false)
Bool Load(BaseDocument *doc, Bool merge=false, Bool loadGlobalColors=false)
Manages file and path names.
Definition: c4d_file.h:94
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())
return OK
Definition: apibase.h:2735
@ LOAD
Load dialog.
@ SCENES
3D scene files.

Presets

Color swatches can also be stored in the preset library:

To make work with presets easier these utility functions exist:

  • ColorSwatchData::PresetExists(): Returns true if the given preset name already exists.
  • ColorSwatchData::ValidPreset(): Returns true if the given URL points to a valid preset.
  • ColorSwatchData::GetPresetDirectory(): Returns the user's default Color Swatch Preset directory.
  • ColorSwatchData::browserPresetType: The ID of color swatch preset objects.
// // 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
// if (!ColorSwatchData::PresetExists(presetName))
// {
// // construct url
// SDKBrowserURL presetUrl = ColorSwatchData::GetPresetDirectory();
// presetUrl += presetName;
//
// // save preset
// if (!colorSwatchData->SavePreset(presetUrl, "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());
}
}
ColorSwatchGroup * AddGroup(SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT, const String &name=String(), Bool selected=false, Int insertAt=-1, const ColorAlphaArray &colors=ColorAlphaArray())
String GetName() const

Further utility functions are:

Further Reading