c4d.modules.colorchooser.ColorSwatchData

class c4d.modules.colorchooser.ColorSwatchData

This type handles the Swatch Data stored globally, in a BaseDocument or a preset.

It holds 2 kinds of groups:

• A global color group that is shared between all Cinema 4D documents and has special methods to handle it.

• Document-based color groups stored in a Cinema 4D document.

New in version R18.011.

Methods Signatures

ColorSwatchData.__init__(self[, doc, global_])

Creates a new swatch data.

ColorSwatchData.Load(self, doc[, merge, ...])	Loads color groups.
ColorSwatchData.Save(self, doc[, globalColors])	Saves the document-based color groups into the given document.
ColorSwatchData.Merge(self, data)	Merges groups from data.
ColorSwatchData.CopyFrom(self, data)	Copies color swatch data.
ColorSwatchData.GetGroupCount(self[, category])	Returns the number of groups stored in category.
ColorSwatchData.GetGroupAtIndex(self, index[, category])	Retrieves the group at the given index.
ColorSwatchData.SetGroupAtIndex(self, index, group[, ...])	Replaces the group at the given index.
ColorSwatchData.AddGroup(self[, category, name, ...])	Adds a new group.
ColorSwatchData.InsertGroup(self, group[, ...])	Inserts an existing group.
ColorSwatchData.RemoveGroup(self, index[, category])	Removes the document-based group at the given index.
ColorSwatchData.RemoveSelectedItems(self)	Removes all selected groups and colors, including selected global colors.
ColorSwatchData.Reset(self)	Removes all groups and colors, including globals.

Methods Documentation

ColorSwatchData.__init__(self, doc=None, global_=False)

Creates a new swatch data.

Parameters

• doc (Optional[c4d.documents.BaseDocument]) – Optional document to load swatches from.

• global (Optional[bool]) – If True the Global Swatch Group will be loaded.

ColorSwatchData.Load(self, doc, merge=False, globalColors=False)

Loads color groups.

Parameters

• doc (c4d.documents.BaseDocument) – The document to load the color groups from.

• merge (Optional[bool]) –

  If True the colors of the given document are merged with the stored colors.

  Otherwise the existing colors are discarded (default).

• globalColors (Optional[bool]) –

  New in version R20: If True the global colors are loaded.

Return type

bool

Returns

True if successful, otherwise False.

ColorSwatchData.Save(self, doc, globalColors=False)

Saves the document-based color groups into the given document.

Parameters

• doc (c4d.documents.BaseDocument) – The document to store the color groups into.

• globalColors (Optional[bool]) –

  New in version R20: If True the global colors are saved.

Return type

bool

Returns

True if successful, otherwise False.

ColorSwatchData.Merge(self, data)

Merges groups from data.

Parameters

data (c4d.modules.colorchooser.ColorSwatchData) – The data to merge groups from.

Return type

bool

Returns

True if the groups were successfully merged, otherwise False.

ColorSwatchData.CopyFrom(self, data)

Copies color swatch data.

Parameters

data (c4d.modules.colorchooser.ColorSwatchData) – The data to copy groups from.

Return type

bool

Returns

True if the color swatch data was successfully copied, otherwise False.

ColorSwatchData.GetGroupCount(self, category=SWATCH_CATEGORY_DOCUMENT)

Returns the number of groups stored in category.

Parameters

category (Optional[int]) –

New in version R20: The group category:

SWATCH_CATEGORY_GLOBAL	Global.
SWATCH_CATEGORY_DOCUMENT	Document.

Return type

int

Returns

The number of color groups.

ColorSwatchData.GetGroupAtIndex(self, index, category=SWATCH_CATEGORY_DOCUMENT)

Retrieves the group at the given index.

Parameters

• index (int) – The index of the color group. Must be 0 <= index < GetGroupCount().

• category (Optional[int]) –

  New in version R20: The group category:

  SWATCH_CATEGORY_GLOBAL	Global.
  SWATCH_CATEGORY_DOCUMENT	Document.

Return type

Optional[c4d.modules.colorchooser.ColorSwatchGroup]

Returns

The swatch group or None.

ColorSwatchData.SetGroupAtIndex(self, index, group, category=SWATCH_CATEGORY_DOCUMENT)

Replaces the group at the given index.

Parameters

• index (int) – The index of the color group. Must be 0 <= index < GetGroupCount().

• group (c4d.modules.colorchooser.ColorSwatchGroup) – The group to set.

• category (Optional[int]) –

  New in version R20: The group category:

  SWATCH_CATEGORY_GLOBAL	Global.
  SWATCH_CATEGORY_DOCUMENT	Document.

Return type

bool

Returns

True if the group was successfully set, otherwise False.

ColorSwatchData.AddGroup(self, category=SWATCH_CATEGORY_DOCUMENT, name='', selected=False, insertAt=- 1, colors=None)

Adds a new group.

Parameters

• category (Optional[int]) –

  New in version R20: The group category:

  SWATCH_CATEGORY_GLOBAL	Global.
  SWATCH_CATEGORY_DOCUMENT	Document.

• name (str) – The name of the new group. If empty the default string “Untitled” will be used.

• selected (bool) – The initial selection state of the new group.

• insertAt (int) – The index of the new group (the list size will increase and the existing elements will be moved) or -1 to add it to the end of the list (default).

• colors (Optional[List[maxon.ColorA]]) – The colors to fill the group with.

Return type

Optional[c4d.modules.colorchooser.ColorSwatchGroup]

Returns

The new swatch group or None.

ColorSwatchData.InsertGroup(self, group, insertAt=- 1, category=SWATCH_CATEGORY_DOCUMENT)

Inserts an existing group.

Parameters

• group (c4d.modules.colorchooser.ColorSwatchGroup) – The group to insert.

• insertAt (Optional[int]) – The index of the new group (the list size will increase and the existing elements will be moved) or -1 to add it to the end of the list (default).

• category (Optional[int]) –

  New in version R20: The group category:

  SWATCH_CATEGORY_GLOBAL	Global.
  SWATCH_CATEGORY_DOCUMENT	Document.

Return type

bool

Returns

True if the group was successfully inserted, otherwise False.

ColorSwatchData.RemoveGroup(self, index, category=SWATCH_CATEGORY_DOCUMENT)

Removes the document-based group at the given index.

Parameters

• index (int) – The index of the color group to remove. Must be 0 <= index < GetGroupCount().

• category (Optional[int]) –

  New in version R20: The group category:

  SWATCH_CATEGORY_GLOBAL	Global.
  SWATCH_CATEGORY_DOCUMENT	Document.

Return type

bool

Returns

True if the group was successfully removed, otherwise False.

ColorSwatchData.RemoveSelectedItems(self)

Removes all selected groups and colors, including selected global colors.

ColorSwatchData.Reset(self)

Removes all groups and colors, including globals.