About

A ColorSwatchGroup stores multiple colors as maxon::ColorA. The group itself and the colors can be selected. ColorSwatchGroup elements are stored and handled using ColorSwatchData objects. 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(ConstDescID(DescLevel(MATERIAL_COLOR_COLOR)), rgb, DESCFLAGS_SET::NONE);
          doc->InsertMaterial(mat);
        }
      }
    }
  }

Allocation/Deallocation

ColorSwatchGroups can be created using the usual tools. This is typically not needed.

ColorSwatchGroup::Alloc(): Creates a new ColorSwatchGroup.
ColorSwatchGroup::Free(): Deletes the given ColorSwatchGroup.

Access

ColorSwatchGroup elements are stored in a ColorSwatchData object. See ColorSwatchData Color Groups

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::RemoveGroup(): Removes the group with the given index.
ColorSwatchData::RemoveSelectedItems(): Removes selected groups and colors.

Selection

A ColorSwatchGroup can be selected:

ColorSwatchGroup::IsGroupSelected(): Returns true if the group is selected.
ColorSwatchGroup::SelectGroup(): Selects or deselects the group.

  // This example loops through all groups and prints the names of the selected groups.
 
  const Int groupCount = colorSwatchData->GetGroupCount();
  for (Int i = 0; i < groupCount; ++i)
  {
    const ColorSwatchGroup* const group = colorSwatchData->GetGroupAtIndex(i);
    if (group == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // check if a group could be accessed
    // and if that group is selected
    if (group->IsGroupSelected())
    {
      ApplicationOutput("Group " + group->GetName() + " is selected.");
    }
  }

Name

A ColorSwatchGroup can be identified by a name:

ColorSwatchGroup::GetName(): Returns the name of the group.
ColorSwatchGroup::SetName(): Sets the name of the group.

  // This example adds a new color group.
 
  ColorSwatchGroup* const group = colorSwatchData->AddGroup();
  if (group == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  group->SetName("This is a new group");

Colors

A ColorSwatchGroup stores multiple colors and their selection state. The colors are obtained with:

ColorSwatchGroup::GetColorCount(): Returns the number of stored colors.
ColorSwatchGroup::GetColor(): Returns the color stored at the given index.
ColorSwatchGroup::GetColors(): Copies the colors to the given maxon::BaseArray.

    // This example prints the values of all colors of the given group.
 
    const Int colorCount = group->GetColorCount();
    for (Int c = 0; c < colorCount; ++c)
    {
      maxon::ColorA color;
 
      // access the color with the index 'c'
      if (!group->GetColor(c, color))
        return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
      ApplicationOutput("Color: @", color);
    }

Colors can be edited with:

ColorSwatchGroup::GetColorEditable(): Returns a pointer to the color at the given index.
ColorSwatchGroup::SetColor(): Sets the color and selection status at the given index.

New colors are added with:

ColorSwatchGroup::AddColor(): Adds the given color to the group.
ColorSwatchGroup::AddColors(): Adds the colors stored in the given maxon::BaseArray to the group.

      // This example adds ten random colors to the given group.
 
      Random random;
 
      for (Int c = 0; c < 10; ++c)
      {
        const maxon::Float  r = random.Get01();
        const maxon::Float  g = random.Get01();
        const maxon::Float  b = random.Get01();
        const maxon::ColorA color(r, g, b, 1.0);
        group->AddColor(color, false);
      }
 
      group->SortColors();

The selection status of a color can be utilized with these functions:

ColorSwatchGroup::IsColorSelected(): Returns true if the color stored at the given index is selected.
ColorSwatchGroup::SelectColor(): Selects or deselects the color at the given index.
ColorSwatchGroup::RemoveSelectedColors(): Removes selected colors from the group.
ColorSwatchGroup::InvertSelection(): Switches the selection status for all colors.

Further utility functions are:

ColorSwatchGroup::RemoveColor(): Removes the color stored at the given index.
ColorSwatchGroup::HasDuplicatedColors(): Returns true if the group contains duplicated colors.
ColorSwatchGroup::RemoveDuplicatedColors(): Removes duplicated colors from the group.
ColorSwatchGroup::SortColors(): Sorts the colors based on their HSV values.
ColorSwatchGroup::Reset(): Removes all colors.
ColorSwatchGroup::Merge(): Merges the colors from the given ColorSwatchGroup.

Table of Contents