ColorSwatchData Class Reference

#include <lib_colorchooser.h>

Detailed Description

This class 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.
Since
R18

Public Member Functions

Bool Load (BaseDocument *doc, Bool merge=false, Bool loadGlobalColors=false)
 
Bool Save (BaseDocument *doc, Bool saveGlobalColors=false)
 
Bool LoadPreset (const String &name, Bool merge=true)
 
Bool LoadPreset (const SDKBrowserURL &url, Bool merge=true)
 
Bool SavePreset (const String &name, const String &author=String(), const String &info=String(), Bool forceOverwrite=false)
 
Bool SavePreset (const SDKBrowserURL &url, const String &author=String(), const String &info=String(), Bool forceOverwrite=false)
 
Bool Merge (ColorSwatchData *data, Bool mergeGlobalColors=false)
 
Bool CopyFrom (ColorSwatchData *data)
 
Int GetGroupCount (SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT) const
 
ColorSwatchGroupGetGroupAtIndex (Int index, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
 
Bool SetGroupAtIndex (Int index, ColorSwatchGroup *group, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
 
ColorSwatchGroupAddGroup (SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT, const String &name=String(), Bool selected=false, Int insertAt=-1, const ColorAlphaArray &colors=ColorAlphaArray())
 
Bool InsertGroup (ColorSwatchGroup *group, Int insertAt=-1, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
 
Bool RemoveGroup (Int index, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
 
Bool RemoveSelectedItems ()
 
void Reset ()
 

Static Public Member Functions

static Bool PresetExists (const String &name, maxon::BaseArray< SDKBrowserURL > *urls=nullptr)
 
static Bool ValidPreset (const SDKBrowserURL &url)
 
static SDKBrowserURL GetPresetDirectory ()
 

Private Member Functions

 ColorSwatchData ()
 
 ~ColorSwatchData ()
 

Alloc/Free

static ColorSwatchDataAlloc (BaseDocument *doc=nullptr, Bool global=false)
 
static void Free (ColorSwatchData *&p)
 

Constructor & Destructor Documentation

◆ ColorSwatchData()

ColorSwatchData ( )
private

◆ ~ColorSwatchData()

~ColorSwatchData ( )
private

Member Function Documentation

◆ Alloc()

static ColorSwatchData* Alloc ( BaseDocument doc = nullptr,
Bool  global = false 
)
static

Allocates a swatch data. Destroy the allocated swatch data with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters
[in]docOptional document to load swatches from.
[in]globalIf true the Global Swatch Group will be loaded.
Returns
The allocated swatch data, or nullptr if the allocation failed.

◆ Free()

static void Free ( ColorSwatchData *&  p)
static

Destructs swatch data allocated with Alloc(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters
[in]pThe swatch data to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

◆ Load()

Bool Load ( BaseDocument doc,
Bool  merge = false,
Bool  loadGlobalColors = false 
)

Loads color groups from the given document and/or global colors.

Parameters
[in]docThe given document. Can be nullptr if only global colors must be loaded.
[in]mergeIf true the colors are merged with the stored colors. Otherwise the
[in]loadGlobalColorsIf true the global colors are loaded.existing colors are discarded.
Returns
true if success, otherwise false.

◆ Save()

Bool Save ( BaseDocument doc,
Bool  saveGlobalColors = false 
)

Saves the color groups to the given document and/or the global colors.

Parameters
[in]docThe document to store the color groups. Can be nullptr if only global colors must be saved.
[in]saveGlobalColorsIf true the global colors are saved.
Returns
true if success, otherwise false.

◆ LoadPreset() [1/2]

Bool LoadPreset ( const String name,
Bool  merge = true 
)

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

See also
GetPresetDirectory()
Parameters
[in]nameThe preset name to load.
[in]mergeSet to true to merge the preset data with current data, set to false to replace data.
Returns
true if success, otherwise false.

◆ LoadPreset() [2/2]

Bool LoadPreset ( const SDKBrowserURL url,
Bool  merge = true 
)

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

Parameters
[in]urlThe preset url.
[in]mergeSet to true to merge the preset data with current data, set to false to replace data.
Returns
true if success, otherwise false.

◆ SavePreset() [1/2]

Bool SavePreset ( const String name,
const String author = String(),
const String info = String(),
Bool  forceOverwrite = false 
)

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

Parameters
[in]nameThe preset name.
[in]authorThe preset author.
[in]infoPreset additional info.
[in]forceOverwriteSet to true to force overwriting the preset in case it already exists.
Returns
true if data was saved, otherwise false.

◆ SavePreset() [2/2]

Bool SavePreset ( const SDKBrowserURL url,
const String author = String(),
const String info = String(),
Bool  forceOverwrite = false 
)

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

Parameters
[in]urlThe url to save preset to. Must include the preset name and must point to an existing library. Example: SDKBrowserURL presetToSaveURL = ColorSwatchData::GetPresetDirectory() + "MyPreset"
[in]authorThe preset author.
[in]infoPreset additional info.
[in]forceOverwriteSet to true to force overwrite the preset in case it already exists.
Returns
true if data was saved, otherwise false.

◆ PresetExists()

static Bool PresetExists ( const String name,
maxon::BaseArray< SDKBrowserURL > *  urls = nullptr 
)
static

Checks if any preset with given name exists at user's Color Swatch Preset directory, including subdirectories.

Parameters
[in]nameThe preset name.
[out]urlsOptionally set here a pointer to an array that will be filled with all urls pointing to a Color Swatch preset with the given name.
Returns
true if any preset with the given name found, otherwise false.

◆ ValidPreset()

static Bool ValidPreset ( const SDKBrowserURL url)
static

Checks if the given URL points to a valid Color Swatch preset.

Parameters
[in]urlThe url to check.
Returns
true if the URL points to a valid Color Swatch preset, otherwise false.

◆ GetPresetDirectory()

static SDKBrowserURL GetPresetDirectory ( )
static

Gets the user's default Color Swatch Preset directory.

Returns
The preset directory.

◆ Merge()

Bool Merge ( ColorSwatchData data,
Bool  mergeGlobalColors = false 
)

Merges groups from data.

Parameters
[in]dataThe data to merge groups from.
[in]mergeGlobalColorsIf true the global colors will be merged inside the global group.
Returns
true if successful, otherwise false.

◆ CopyFrom()

Bool CopyFrom ( ColorSwatchData data)

Copies color swatch data.

Parameters
[in]dataSwatch data to copy from.
Returns
true if successful, otherwise false.

◆ GetGroupCount()

Int GetGroupCount ( SWATCH_CATEGORY  category = SWATCH_CATEGORY::DOCUMENT) const

Returns the number of groups stored in category.

Parameters
[in]categoryThe group category.
Returns
The number of color groups.

◆ GetGroupAtIndex()

ColorSwatchGroup* GetGroupAtIndex ( Int  index,
SWATCH_CATEGORY  category = SWATCH_CATEGORY::DOCUMENT 
)

Returns the document-based group at the given index.

Parameters
[in]indexThe index of the color group. Must be 0 <= index < GetGroupCount().
[in]categoryThe group category.
Returns
The Swatch group or nullptr. Swatch data owns the pointed object.

◆ SetGroupAtIndex()

Bool SetGroupAtIndex ( Int  index,
ColorSwatchGroup group,
SWATCH_CATEGORY  category = SWATCH_CATEGORY::DOCUMENT 
)

Replaces the group at given index.

Parameters
[in]indexThe index of the color group. Must be 0 <= index < GetGroupCount().
[in]groupThe group to copy from.
[in]categoryThe group category.
Returns
true if successful, otherwise false.

◆ AddGroup()

ColorSwatchGroup* AddGroup ( SWATCH_CATEGORY  category = SWATCH_CATEGORY::DOCUMENT,
const String name = String(),
Bool  selected = false,
Int  insertAt = -1,
const ColorAlphaArray colors = ColorAlphaArray() 
)

Adds a new document-based group.

Parameters
[in]categoryThe category where the group will be inserted.
[in]nameThe name of the new group. If empty the default string "Untitled" will be used.
[in]selectedThe initial selection state of the new group.
[in]insertAtThe index of the new group (the list size will increase and the existing elements are moved) or -1 to add it to the end of the list.
[in]colorsColors to fill the group with.
Returns
The new Swatch Group or nullptr. The Swatch Data owns the pointed Swatch Group.

◆ InsertGroup()

Bool InsertGroup ( ColorSwatchGroup group,
Int  insertAt = -1,
SWATCH_CATEGORY  category = SWATCH_CATEGORY::DOCUMENT 
)

Adds a group.

Parameters
[in]groupThe group to copy from.
[in]insertAtThe index of the new group (the list size will increase and the existing elements are moved) or -1 to add it to the end of the list.
[in]categoryThe group category.
Returns
true if successful, otherwise false.

◆ RemoveGroup()

Bool RemoveGroup ( Int  index,
SWATCH_CATEGORY  category = SWATCH_CATEGORY::DOCUMENT 
)

Removes the group from category at the given index.

Parameters
[in]indexThe index of the color group. Must be 0 <= index < GetGroupCount().
[in]categoryThe group category.
Returns
true if the group was successfully removed, otherwise false.

◆ RemoveSelectedItems()

Bool RemoveSelectedItems ( )

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

Returns
true if any item was successfully removed, otherwise false.

◆ Reset()

void Reset ( )

Removes all groups and colors, including globals.