#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)

static Bool	ValidPreset (const SDKBrowserURL &url)

static SDKBrowserURL	GetPresetDirectory ()

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.

See also: GetPresetDirectory()

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. Example: `SDKBrowserURL presetToSaveURL = ColorSwatchData::GetPresetDirectory() + "MyPreset"`
[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.

◆ ValidPreset()

static Bool ValidPreset ( const SDKBrowserURL & url )

static

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

Parameters

[in] url The 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]	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.

Detailed Description

Public Member Functions

Static Public Member Functions

Private Member Functions

Alloc/Free

Constructor & Destructor Documentation

◆ ColorSwatchData()

◆ ~ColorSwatchData()

Member Function Documentation

◆ Alloc()

◆ Free()

◆ Load()

◆ Save()

◆ LoadPreset() [1/2]

◆ LoadPreset() [2/2]

◆ SavePreset() [1/2]

◆ SavePreset() [2/2]

◆ PresetExists()

◆ ValidPreset()

◆ GetPresetDirectory()

◆ Merge()

◆ CopyFrom()

◆ GetGroupCount()

◆ GetGroupAtIndex()

◆ SetGroupAtIndex()

◆ AddGroup()

◆ InsertGroup()

◆ RemoveGroup()

◆ RemoveSelectedItems()

◆ Reset()