The JavaScript class providing information about a specific palette. More...

Public Slots
String	getPath ()
	Returns the folder in which this palette is located. More...

String	getName ()
	Returns the name of this palette. The extension (".plt") is not included. More...

bool	isValid ()
	Returns true if the palette object is valid. More...

bool	isLoaded ()
	Returns true if the palette was successfully loaded from the disk. More...

bool	isNotFound ()
	Returns true if the palette was found at the location specified by the path and name. More...

BaseColor *	getColorByIndex (int index)
	Returns the colour found at the given index. Returns an invalid colour if the index is out of bound or otherwise invalid. More...

BaseColor *	getColorById (String &uniqueId)
	Returns the colour found by the given Id. If the colour is not found, the isValid property will be false. More...

bool	getLock ()
	Try to obtain the database lock. Return true on success, and false on failure. The lock will be held until it is released in script or the ui. Safe to call multiple time to get the lock state. More...

bool	releaseLock ()
	Release access to the palette. Other users will be able to obtain the access rights to the palette. More...

bool	isColorPalette ()
	Returns whether the palette is a colour palette. More...

bool	isTexturePalette ()
	Returns whether the palette is a texture palette. More...

void	setToColorPalette ()
	Sets the type of the palette to be a colour palette. More...

void	setToTexturePalette ()
	Sets the type of the palette to be a texture palette. More...

Color *	createNewColor (int colorType, String &name, QVariant colorData)
	Create a new colour of a given type. More...

Color *	createNewSolidColor (String &name, QVariant colorData)
	Create a new solid colour. More...

Color *	createNewLinearGradientColor (String &name, QVariant colorData)
	Create a new linear gradient colour. More...

Color *	createNewRadialGradientColor (String &name, QVariant colorData)
	Create a new radial gradient colour. More...

Texture *	createNewTexture (String &name, String &filename, bool tiled)
	Create a new texture colour object. More...

Texture *	createNewTexture (String &name, QImage &bitmap, bool tiled)
	Create a new texture from a QImage object (may not be done from the script). More...

BaseColor *	duplicateColor (BaseColor *source)
	Create a duplicate of a colour object - this colorID is unique. More...

BaseColor *	cloneColor (BaseColor *source)
	Create a clone of a colour object - this colorID is identical to original colour. More...

BaseColor *	cloneColor (BaseColor *source, bool replaceOnIDConflict)
	Create a clone of a colour object - resolve the potential ID conflict by either cloning or duplicating the colour. More...

bool	removeColor (String &uniqueId)
	Delete a colour from the palette. More...

bool	moveColor (int index, int beforeIndex)
	Moves a colour at the specified index. More...

bool	acquire (BaseColor *color)
	Move a color to this palette. More...

bool	containsUsedColors (QScriptValue colors)
	Returns true if this palette contains a colour used in a drawing in the scene. More...

Properties
int	nColors
	Number of colours in this palette. More...

String	id
	The palette ID of this palette. More...

int	location
	Returns one of the PaletteLocation constants or -1 if the palette is invalid. More...

int	elementId
	Returns the element id in which the palette is stored if location is PaletteLocation ELEMENT. Returns -1 if the palette is not stored in an element. More...

Detailed Description

The JavaScript class providing information about a specific palette.

A Palette object can be obtained from PaletteList methods like getPaletteByIndex, getPaletteById or createPalette or from the PaletteObjectManager method getPalette. The Palette class defines a palette of colours. It provides access to functionalities of palettes like:

Creating or modifying the colour types.
Reordering, cloning or duplicating the colours of a Palette.
Moving a colour pot from a palette to another.

Note: Functions that modify the state of the palette will try to obtain the database access lock. If the lock cannot be obtained, a JavaScript exception will be thrown.

var paletteList = PaletteObjectManager.getPaletteListByElementId(elementId);
for ( var j = 0; j < paletteList.numPalettes; ++ j )
{
  var myPalette = paletteList.getPaletteByIndex( j );
  var path = myPalette.getPath() + "/" + myPalette.getName();
}

Member Function Documentation

◆ acquire

bool Palette::acquire ( BaseColor * color )

slot

Move a color to this palette.

Will remove the colour from its original palette and move it to this one. Returns false if the colour is invalid or if this is the same palette as the current colour palette. If this palette has a colour with the same colour ID as the source colour, it will return false also.

Parameters

color : The colour to be acquired.

Returns: Returns true if the colour is successfully moved.

◆ cloneColor [1/2]

BaseColor* Palette::cloneColor ( BaseColor * source )

slot

Create a clone of a colour object - this colorID is identical to original colour.

Will create a copy of the colour with all the same values including the colorID. The source must be from another palette otherwise it will return an invalid color.

Parameters

source : The source colour to be cloned.

Returns: Returns the created colour.

◆ cloneColor [2/2]

BaseColor* Palette::cloneColor	(	BaseColor *	source,
		bool	replaceOnIDConflict
	)

slot

Create a clone of a colour object - resolve the potential ID conflict by either cloning or duplicating the colour.

This version allow you to specify whether to replace an already existing color when cloning the palette.

Parameters

source	: The source colour to be cloned.
replaceOnIDConflict	: True to replace an already existing colour when cloning the palette.

Returns: Returns the created colour.

◆ containsUsedColors

bool Palette::containsUsedColors ( QScriptValue colors )

slot

Returns true if this palette contains a colour used in a drawing in the scene.

function checkContainsUsedColors(nodeName)
{
  //nodeName is the full path of a node, such as "Top/Group_Name/Node_Name"
  var layerName = node.getTextAttr(nodeName, 1, "drawing.element.layer");
  var elementId = node.getElementId(nodeName);
  var colorList = [];
  for (var j = 0; j < Drawing.numberOf(elementId); j++)
  {
    var drawingId = Drawing.name(elementId, j);
    var drawingKey = Drawing.Key({ elementId : elementId, layer : layerName, exposure : drawingId });
    var currentList = DrawingTools.getDrawingUsedColors(drawingKey);
    for (var i in currentList)
    {
      colorList.push(currentList[i]);
    }
  }
  var list = PaletteObjectManager.getScenePaletteList();
  for (var i = 0; i < list.numPalettes; i++)
  {
    var palette = list.getPaletteByIndex(i);
    MessageLog.trace(palette.getName());
    MessageLog.trace(palette.containsUsedColors(colorList));
  }
}

Parameters

colors : An array of color ids used in the scene.

Note: The color ids can be retrieved with DrawingTools.getDrawingUsedColors()

Returns: True if this palette contains a colour used in a drawing in the scene.

◆ createNewColor

Color* Palette::createNewColor	(	int	colorType,
		String &	name,
		QVariant	colorData
	)

slot

Create a new colour of a given type.

Parameters

colorType	: colorType can be: ColorType.SOLID_COLOR ColorType.LINEAR_GRADIENT ColorType.RADIAL_GRADIENT
name	: The name of the colour to be created.
colorData	: Depending on the value of colorType argument, colorData has to be either an array of objects or an object. If the colorType argument is SOLID_COLOR, the colorData must be an object defined like this: { r : 255, g: 0, b: 0, a : 255 } to represent a solid red colour. If the colorType argument is one of the gradients, there must be an array of objects, one for each gradient tack. For example: [ { r : 255, g: 0, b: 0, a : 255, t: 0 }, { r : 0, g: 0, b: 255, a : 255, t: 1 } ] would define a gradient going from red to blue. The t parameter in each object represents the tack position and is a double value going from 0 to 1.

Returns: Returns the created color.

◆ createNewLinearGradientColor

Color* Palette::createNewLinearGradientColor	(	String &	name,
		QVariant	colorData
	)

slot

Create a new linear gradient colour.

Same as createNewColor(ColorType.LINEAR_GRADIENT, name, colorData);

Parameters

name	: The name of the colour to be created.
colorData	: colorData must be an array of objects, one for each gradient tack. For example: [ { r : 255, g: 0, b: 0, a : 255, t: 0 }, { r : 0, g: 0, b: 255, a : 255, t: 1 } ] would define a gradient going from red to blue. The t parameter in each object represents the tack position and is a double value going from 0 to 1.

Returns: Returns the created colour.

◆ createNewRadialGradientColor

Color* Palette::createNewRadialGradientColor	(	String &	name,
		QVariant	colorData
	)

slot

Create a new radial gradient colour.

Same as createNewColor(ColorType.RADIAL_GRADIENT, name, colorData);

Parameters

name	: The name of the colour to be created.
colorData	: colorData must be an array of objects, one for each gradient tack. For example: [ { r : 255, g: 0, b: 0, a : 255, t: 0 }, { r : 0, g: 0, b: 255, a : 255, t: 1 } ] would define a gradient going from red to blue. The t parameter in each object represents the tack position and is a double value going from 0 to 1.

Returns: Returns the created colour.

◆ createNewSolidColor

Color* Palette::createNewSolidColor	(	String &	name,
		QVariant	colorData
	)

slot

Create a new solid colour.

Same as createNewColor(ColorType.SOLID_COLOR, name, colorData);

Parameters

name	: The name of the colour to be created.
colorData	: colorData must be an object defined like this example: { r : 255, g: 0, b: 0, a : 255 } which represents a solid red colour.

Returns: Returns the created colour.

◆ createNewTexture [1/2]

Texture* Palette::createNewTexture	(	String &	name,
		String &	filename,
		bool	tiled
	)

slot

Create a new texture colour object.

Creates a texture pot. Copies the bitmap file internally to the palette.

Parameters

name	: The name of the texture to be created.
filename	: The name of the file to be turned into a texture.
tiled	: Whether or not the texture will be tiled or not.

Returns: Returns the created texture.

◆ createNewTexture [2/2]

Texture* Palette::createNewTexture	(	String &	name,
		QImage &	bitmap,
		bool	tiled
	)

slot

Create a new texture from a QImage object (may not be done from the script).

Creates a texture pot. Will copy the bitmap data internally to the palette.

Parameters

name	: The name of the texture to be created.
bitmap	: The bitmap to be turned into a texture.
tiled	: Whether or not the texture will be tiled or not.

Returns: Returns the created texture.

◆ duplicateColor

BaseColor* Palette::duplicateColor ( BaseColor * source )

slot

Create a duplicate of a colour object - this colorID is unique.

Creates a copy of the colour with all the same values as source except for the colorID which will be a new uniqueID.

Parameters

source : The source colour to be duplicated.

Returns: Returns the created colour.

◆ getColorById

BaseColor* Palette::getColorById ( String & uniqueId )

slot

Returns the colour found by the given Id. If the colour is not found, the isValid property will be false.

Parameters

uniqueId : The id of the colour.

Returns: Returns the colour found by the given Id.

◆ getColorByIndex

BaseColor* Palette::getColorByIndex ( int index )

slot

Returns the colour found at the given index. Returns an invalid colour if the index is out of bound or otherwise invalid.

Parameters

index : The zero based index of the colour.

Returns: Returns the colour found at the given index.

◆ getLock

bool Palette::getLock ( )

slot

Try to obtain the database lock. Return true on success, and false on failure. The lock will be held until it is released in script or the ui. Safe to call multiple time to get the lock state.

Returns: Returns the lock state, true if set.

◆ getName

String Palette::getName ( )

slot

Returns the name of this palette. The extension (".plt") is not included.

Returns: Returns the name of this palette.

◆ getPath

String Palette::getPath ( )

slot

Returns the folder in which this palette is located.

Returns: Returns the folder in which this palette is located.

◆ isColorPalette

bool Palette::isColorPalette ( )

slot

Returns whether the palette is a colour palette.

Returns: Returns true if the palette is a colour palette.

◆ isLoaded

bool Palette::isLoaded ( )

slot

Returns true if the palette was successfully loaded from the disk.

Returns: Returns true if the palette was successfully loaded from the disk.

◆ isNotFound

bool Palette::isNotFound ( )

slot

Returns true if the palette was found at the location specified by the path and name.

Returns: Returns true if the palette was found at the location specified by the path and name.

◆ isTexturePalette

bool Palette::isTexturePalette ( )

slot

Returns whether the palette is a texture palette.

Returns: Returns true if the palette is a texture palette.

◆ isValid

bool Palette::isValid ( )

slot

Returns true if the palette object is valid.

Returns: Returns true if the palette object is valid.

◆ moveColor

bool Palette::moveColor	(	int	index,
		int	beforeIndex
	)

slot

Moves a colour at the specified index.

Moves the colour at given index just before the colour at beforeIndex in the list. Moves the colour at the end if beforeIndex is -1.

Parameters

index	: The index of the colour to be moved.
beforeIndex	: The index of the colour that the color will be moved before.

Returns: Returns true if the colour is successfully moved.

◆ releaseLock

bool Palette::releaseLock ( )

slot

Release access to the palette. Other users will be able to obtain the access rights to the palette.

Returns: Returns true if the lock is successfully released.

◆ removeColor

bool Palette::removeColor ( String & uniqueId )

slot

Delete a colour from the palette.

Permanently delete a colour.

Parameters

uniqueId : The uniqueID of the colour to be removed.

Returns: Returns true if the colour is successfully removed from the palette.

◆ setToColorPalette

void Palette::setToColorPalette ( )

slot

Sets the type of the palette to be a colour palette.

◆ setToTexturePalette

void Palette::setToTexturePalette ( )

slot

Sets the type of the palette to be a texture palette.

Property Documentation

◆ elementId

int Palette::elementId

read

Returns the element id in which the palette is stored if location is PaletteLocation ELEMENT. Returns -1 if the palette is not stored in an element.

◆ id

String Palette::id

read

The palette ID of this palette.

◆ location

int Palette::location

read

Returns one of the PaletteLocation constants or -1 if the palette is invalid.

◆ nColors

int Palette::nColors

read

Number of colours in this palette.

Public Slots

Properties

Detailed Description

Member Function Documentation

◆ acquire

◆ cloneColor [1/2]

◆ cloneColor [2/2]

◆ containsUsedColors

◆ createNewColor

◆ createNewLinearGradientColor

◆ createNewRadialGradientColor

◆ createNewSolidColor

◆ createNewTexture [1/2]

◆ createNewTexture [2/2]

◆ duplicateColor

◆ getColorById

◆ getColorByIndex

◆ getLock

◆ getName

◆ getPath

◆ isColorPalette

◆ isLoaded

◆ isNotFound

◆ isTexturePalette

◆ isValid

◆ moveColor

◆ releaseLock

◆ removeColor

◆ setToColorPalette

◆ setToTexturePalette

Property Documentation

◆ elementId

◆ id

◆ location

◆ nColors