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
ColorSwatchGroup *	GetGroupAtIndex (Int index, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
Bool	SetGroupAtIndex (Int index, ColorSwatchGroup *group, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
ColorSwatchGroup *	AddGroup (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)

Private Member Functions
	ColorSwatchData ()
	~ColorSwatchData ()

Alloc/Free
static ColorSwatchData *	Alloc (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]	doc	Optional document to load swatches from.
[in]	global	If 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]

p

The 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]	doc	The given document. Can be nullptr if only global colors must be loaded.
[in]	merge	If true the colors are merged with the stored colors. Otherwise the
[in]	loadGlobalColors	If 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]	doc	The document to store the color groups. Can be nullptr if only global colors must be saved.
[in]	saveGlobalColors	If 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.

Parameters

[in]	name	The preset name to load.
[in]	merge	Set 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]	url	The preset url.
[in]	merge	Set 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]	name	The preset name.
[in]	author	The preset author.
[in]	info	Preset additional info.
[in]	forceOverwrite	Set 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]	url	The url to save preset to. Must include the preset name and must point to an existing library.
[in]	author	The preset author.
[in]	info	Preset additional info.
[in]	forceOverwrite	Set 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]	name	The preset name.
[out]	urls	Optionally 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.

Merge()

Bool Merge	(	ColorSwatchData *	data,
		Bool	mergeGlobalColors = false
	)

Merges groups from data.

Parameters

[in]	data	The data to merge groups from.
[in]	mergeGlobalColors	If 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]

data

Swatch 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]

category

The 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]	index	The index of the color group. Must be 0 <= index < GetGroupCount().
[in]	category	The 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]	index	The index of the color group. Must be 0 <= index < GetGroupCount().
[in]	group	The group to copy from.
[in]	category	The 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]	category	The category where the group will be inserted.
[in]	name	The name of the new group. If empty the default string "Untitled" will be used.
[in]	selected	The initial selection state of the new group.
[in]	insertAt	The 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]	colors	Colors 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]	group	The group to copy from.
[in]	insertAt	The 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]	category	The 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]	index	The index of the color group. Must be 0 <= index < GetGroupCount().
[in]	category	The 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.