ColorSwatchData Manual

Table of Contents

• About
• Allocation/Deallocation
• Document Colors
• Presets
• Color Groups
• Further Reading

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
  AutoFree<ColorSwatchData> freeData;
  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)
      {
        maxon::ColorA color;
        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 };
          mat->SetParameter(MATERIAL_COLOR_COLOR, rgb, DESCFLAGS_SET::NONE);
          doc->InsertMaterial(mat);
        }
      }
    }
  }

Allocation/Deallocation

ColorSwatchData instances are created with the usual tools:

• ColorSwatchData::Alloc(): Creates a new ColorSwatchData object. If the second argument is set to true, the global group is loaded.
• ColorSwatchData::Free(): Destroys the given ColorSwatchData.

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

Document Colors

Color groups can be stored in a BaseDocument:

• ColorSwatchData::Load(): Loads the color groups from the given BaseDocument.
• ColorSwatchData::Save(): Saves the color groups to the given 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:

• ColorSwatchData::LoadPreset(): Loads the color groups from the given preset.
• ColorSwatchData::SavePreset(): Saves the color gorups to the given preset.

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

• ColorSwatchData::GetGroupCount(): Returns the number of groups stored.
• ColorSwatchData::GetGroupAtIndex(): Returns the group stored at the given index.
• ColorSwatchData::AddGroup(): Adds a new group to the ColorSwatchData.
• ColorSwatchData::SetGroupAtIndex(): Replaces the group at given index.
• ColorSwatchData::InsertGroup(): Adds the given group.
• ColorSwatchData::RemoveGroup(): Removes the group with the given index.
• ColorSwatchData::RemoveSelectedItems(): Removes selected groups and colors.

  // 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:

• ColorSwatchData::Merge(): Merges the groups with the groups stored in the given object.
• ColorSwatchData::CopyFrom(): Copies the data from the given ColorSwatchData object.
• ColorSwatchData::Reset(): Removes all stored groups and colors, including globals.

Further Reading

• ColorSwatchGroup Manual
• Color Functions Manual
• BaseDocument Manual