The Drawing JavaScript global object. Iterate and manipulate the drawings of an element node. More...

Public Slots
int	numberOfLayers (int elementId)
	Returns the number of drawing layers in the element. More...

String	layer (int elementId, int drawingLayerIndex)
	Returns the drawing layer name. More...

int	numberOf (int elementId)
	Returns the number of drawings in the element. More...

String	name (int elementId, int drawingIndex)
	Returns the drawing id. More...

bool	isExists (int elementId, String timing)
	Returns true if the given drawing exists in this element. More...

String	generateUniqueTiming (int elementId, String baseTiming)

String	generateUniqueTiming (int elementId)

bool	create (int elementId, String timing, bool fileExists, bool storeInProjectFolder=false)
	Creates a new drawing inside an element. More...

bool	importDrawing (int elementId, String timing, QScriptValue filepath)

String	filename (int elementId, String drawingName)
	Returns the filename of this drawing on disk or in a vfs folder. More...

QScriptValue	filepath (int elementId, String drawingName)
	Returns the filepath of this drawing on disk or in a vfs folder. More...

QScriptValue	Key (QScriptValue object)
	Create a drawing key which can be used to test the availability of a drawing. More...

Detailed Description

The Drawing JavaScript global object. Iterate and manipulate the drawings of an element node.

var nodes = node.subNodes("Top");
for(var nodeIndex in nodes)
{
  var layerName = node.getTextAttr(nodes[nodeIndex], 1, "drawing.element.layer");
  var elementId = node.getElementId(nodes[nodeIndex]);
  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 });
    DrawingTools.recolorDrawing(drawingKey, colorMapping);
  }
}

Member Function Documentation

◆ create

bool Drawing::create	(	int	elementId,
		String	timing,
		bool	fileExists,
		bool	storeInProjectFolder = `false`
	)

slot

Creates a new drawing inside an element.

Create a new empty drawing inside the given element. The drawing file will physically exists in the temporary folder until the project is saved. Then, the file will reside in (scene folder)/elements/MyElement/ (where MyElement is the name of the element linked to the given elementId).

var nodePath = "Top/MyDrawing";
var elementId = node.getElementId(nodePath);
// Add the drawing to the scene. For now it's just a placeholder until we copy the drawing file into the temp or project folder.
var exposure = "MyExposure"; // exposure in the Xsheet
Drawing.create(elementId, exposure, true);
// Copy the external image file into the temp (if the file wasn't saved since the addition of the element node) / project (if the element was saved) folder
var filename = sourceFileName(frameIndex, lowQuality);
var sourceFile = "c:/myFolder/MyExternalImage.png;  // The extension of the file must match the file format of the element. @sa element::add
var destinationFile = Drawing.filename(elementId, exposure);
copyFile(sourceFile, destinationFile);  // @sa PermanentFile
// Set the added drawing as the current drawing on the element node's drawing column.
var drawingColumn = node.linkedColumn(nodePath, "DRAWING.ELEMENT");
column.setEntry(drawingColumn, 1, frame.current(), exposure);

See also: element::add.

Parameters

elementId	: The unique id of the element.
timing	: The proposed drawing name.
fileExists	: Used to indicate that the drawing exists. By default, drawings exist in the temporary folder.
storeInProjectFolder	: Indicate that the drawing exits in the project folder, not in a temporary folder.

Returns: Returns true if new drawing created. Returns false if not.

◆ filename

String Drawing::filename	(	int	elementId,
		String	drawingName
	)

slot

Returns the filename of this drawing on disk or in a vfs folder.

This filename may be in the temp folder or project folder. Before the project is actually saved, the temporary folder is where the drawing must reside to be found by the application.

Parameters

elementId	: The unique id of the element.
drawingName	: The drawing name.

Returns: Returns the 'load' filename of this drawing.

◆ filepath

QScriptValue Drawing::filepath	(	int	elementId,
		String	drawingName
	)

slot

Returns the filepath of this drawing on disk or in a vfs folder.

This filename may be in the temp folder or project folder. Before the project is actually saved, the temporary folder is where the drawing must reside to be found by the application.

Parameters

elementId	: The unique id of the element.
drawingName	: The drawing name.

Returns: Returns an object containing the location of this drawing.

◆ generateUniqueTiming [1/2]

String Drawing::generateUniqueTiming	(	int	elementId,
		String	baseTiming
	)

slot

Returns a timing that does not exist in the element and could be passed to importDrawing().

Parameters

elementId	: The unique id of the element.
baseTiming	: The base drawing name. Can be empty.

◆ generateUniqueTiming [2/2]

String Drawing::generateUniqueTiming ( int elementId )

slot

◆ importDrawing

bool Drawing::importDrawing	(	int	elementId,
		String	timing,
		QScriptValue	filepath
	)

slot

Imports a new drawing inside an element and assigns it the timing passed in argument. If the timing exists, the file will be replaced.

// This piece of code imports a specified drawing in the selected read element
// at the current frame. It makes sure to create a unique exposure name for the drawing.
var filename = "/tmp/myDrawing.tvg";
var n = selection.selectedNode(0);
if (!n) return;
var elemId = node.getElementId(n);
var newTiming = Drawing.generateUniqueTiming(elemId);
scene.beginUndoRedoAccum("Import drawing: " + filename);
Drawing.importDrawing(elemId, newTiming, filename);
var cid = node.linkedColumn(n, "DRAWING.ELEMENT");
column.setEntry(cid, 1, frame.current(), newTiming);
scene.endUndoRedoAccum();

Parameters

elementId	: The unique id of the element.
timing	: The proposed drawing name.
filepath	: The file path to import.

Returns: Returns true if the drawing could be successfully imported. Returns false if not.

◆ isExists

bool Drawing::isExists	(	int	elementId,
		String	timing
	)

slot

Returns true if the given drawing exists in this element.

Parameters

elementId	: The unique id of the element.
timing	: The drawing name.

◆ Key

QScriptValue Drawing::Key ( QScriptValue object )

slot

Create a drawing key which can be used to test the availability of a drawing.

Create a drawing key from an object having one of the following property set.

Parameters

object

an object with the following properties (see the example below).

// Point to a drawing from the file system
var fileDrawingKey =
{
  filename : "C:/MySceneFolder/elements/Drawing/Drawing-1.tvg"
};
var drawingKey = Drawing.Key(fileDrawingKey);
if(!drawingKey.isValid)
  return;

// Point to the drawing of a node exposed to a given frame
var nodeDrawingKey =
{
  node : "Top/MyDrawing",
  frame : 1
};
var drawingKey = Drawing.Key(nodeDrawingKey);
if(!drawingKey.isValid)
  return;

// Point to a drawing from an element
var exposureDrawingKey =
{
  elementId : 1,
  exposure : "2",
  layer : "Drawing_1" // [Optional] Name of the synced drawing layer. Get it from the "DRAWING.ELEMENT.LAYER" attribute from an element node. DO NOT SPECIFY if the drawing isn't a drawing layer.
};
var drawingKey = Drawing.Key(exposureDrawingKey);
if(!drawingKey.isValid)
  return;

As a more complete example, here's how to get the properties of a drawing key from an element node.

var elementNode = "Top/MyDrawing";
// Get the name of the synced layer.
var layerAttr = node.getAttr(elementNode, frame.current(), "DRAWING.ELEMENT.LAYER");
var layerName = layerAttr.textValue();
var elementId = node.getElementId(elementNode);
var drawingColumn = node.linkedColumn(elementNode, "DRAWING.ELEMENT");
var exposure = column.getEntry(drawingColumn, 1, frame.current());
var drawingKey;
if(layerName.length)
{
  drawingKey = Drawing.Key(elementId, exposure, layerName);
}
else
{
  // The given node isn't a synced layer, do not specify the layer name.
  drawingKey = Drawing.Key(elementId, exposure);
}

◆ layer

String Drawing::layer	(	int	elementId,
		int	drawingLayerIndex
	)

slot

Returns the drawing layer name.

Parameters

elementId	: The unique id of the element.
drawingLayerIndex	: The drawing layer index (if the index is 0 it will return the default drawing layer name, which is empty).

◆ name

String Drawing::name	(	int	elementId,
		int	drawingIndex
	)

slot

Returns the drawing id.

Parameters

elementId	: The unique id of the element.
drawingIndex	: The drawing index.

◆ numberOf

int Drawing::numberOf ( int elementId )

slot

Returns the number of drawings in the element.

Parameters

elementId : The unique id of the element.

Returns: Returns the number of drawings in the element.

◆ numberOfLayers

int Drawing::numberOfLayers ( int elementId )

slot

Returns the number of drawing layers in the element.

Parameters

elementId : The unique id of the element.

Returns: Returns the number of drawing layers in the element (there's always at least one drawing layer, i.e. the default layer).

Public Slots

Detailed Description

Member Function Documentation

◆ create

◆ filename

◆ filepath

◆ generateUniqueTiming [1/2]

◆ generateUniqueTiming [2/2]

◆ importDrawing

◆ isExists

◆ Key

◆ layer

◆ name

◆ numberOf

◆ numberOfLayers