ColorSwatchData

New in version R18.011.

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.

Members

ColorSwatchData.__init__(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.
Return type:

c4d.modules.colorchooser.ColorSwatchData

Returns:

A new swatch data.

ColorSwatchData.Load(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(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.LoadPresetByName(name, merge=False)

Loads the document-based swatch groups of the first preset with the given name found in the user’s Color Swatch Preset directory, including subdirectories.

Parameters:
  • name (str) – The preset name to load.
  • merge (Optional[bool]) – If True the colors of the preset are merged with the stored colors. Otherwise the existing colors are discarded (default).
Return type:

bool

Returns:

True if successful, otherwise False.

ColorSwatchData.LoadPresetByURL(url, merge)

Loads the document-based swatch groups of the given preset.

Parameters:
  • url (str) – The preset url.
  • merge (c4d.documents.BaseDocument) – If True the colors of the preset are merged with the stored colors. Otherwise the existing colors are discarded (default).
Return type:

bool

Returns:

True if successful, otherwise False.

ColorSwatchData.SavePresetByName(name, author="", info="", forceOverwrite=False)

Saves the document-based groups as a Color Swatch preset.

Parameters:
  • name (str) – The preset name.
  • author (Optional[str]) – The preset author.
  • info (Optional[str]) – Preset additional info.
  • forceOverwrite (Optional[bool]) – Set to True to force overwriting the preset in case it already exists.
Return type:

bool

Returns:

True if the preset was saved successfully, otherwise False.

ColorSwatchData.SavePresetByURL(url, author="", info="", forceOverwrite=False)

Saves the document-based groups as a Color Swatch preset.

Parameters:
  • url (str) –
    The url to save the preset to. Must include the preset name and must point to an existing library.
    Example: presetToSaveURL = c4d.modules.colorchooser.GetColorSwatchPresetDirectory() + “MyPreset”
  • author (Optional[str]) – The preset author.
  • info (Optional[str]) – The preset additional info.
  • forceOverwrite (Optional[bool]) – Set to True to force overwriting the preset in case it already exists.
Return type:

bool

Returns:

True if the preset was saved successfully, otherwise False.

ColorSwatchData.Merge(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(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(category)

Returns the number of groups stored in category.

Parameters:category (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(index, category=c4d.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:

c4d.modules.colorchooser.ColorSwatchGroup

Returns:

The swatch group or None.

ColorSwatchData.SetGroupAtIndex(index, group, category=c4d.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(category=c4d.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 (Optional[str]) – The name of the new group. If empty the default string “Untitled” will be used.
  • selected (Optional[bool]) – The initial selection state of the new group.
  • 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).
  • colors (List[maxon.ColorA]) – The colors to fill the group with.
Return type:

c4d.modules.colorchooser.ColorSwatchGroup

Returns:

The new swatch group or None.

ColorSwatchData.InsertGroup(group, insertAt=-1, category=c4d.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(index, category=c4d.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()

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

ColorSwatchData.Reset()

Removes all groups and colors, including globals.