The copyPaste JavaScript global object. Copy paste to/from templates. Note: 'Paste Special' options will only take effect if activated beforehand, usePasteSpecial() for more details. More...

Public Slots
String	createTemplateFromSelection (String name, String &path)
	Creates template from the current selection in the scene, using only the current drawing versions. More...

void	useCreateTemplateSpecial (bool flag, bool addModellingDir=true, bool addScanFiles=true, bool includeDefaultCameraName=true)
	Allows 2 extra options in the template creation. More...

bool	pasteTemplateIntoScene (String &templateSrcPath, String &insertColumnName, int insertFrame)
	Pastes the template into the scene. More...

bool	pasteTemplateIntoGroup (String &srcPath, String &groupName, int insertFrame)
	Pastes the template into a group of the scene. More...

bool	pasteActionTemplateIntoNode (String &srcPath, String &nodeName, int insertFrame, QScriptValue &compositionOptions=QScriptValue())
	Pastes the action template into the scene and excludes nodes that are in the list. More...

void	usePasteSpecial (bool flag)
	Enables PasteSpecial. More...

void	setExtendScene (bool flag)
	PasteSpecial Structure value. Default value is false. More...

Node Section
void	setPasteSpecialCreateNewColumn (bool flag)
	PasteSpecial Structure value. Default value is false. More...

void	setPasteSpecialElementTimingColumnMode (String mode)
	PasteSpecial Structure value. Default value is "ELEMENT_AS_ELEMENT_AND_TIMING_AS_TIMING". More...

Pegs and Functions Section
void	setPasteSpecialAddRemoveMotionKeyFrame (bool flag)
	PasteSpecial Structure value. Default value is true. More...

void	setPasteSpecialAddRemoveVelocityKeyFrame (bool flag)
	PasteSpecial Structure value. Default value is true. More...

void	setPasteSpecialAddRemoveAngleKeyFrame (bool flag)
	PasteSpecial Structure value. Default value is true. More...

void	setPasteSpecialAddRemoveSkewKeyFrame (bool flag)
	PasteSpecial Structure value. Default value is true. More...

void	setPasteSpecialAddRemoveScalingKeyFrame (bool flag)
	PasteSpecial Structure value. Default value is true. More...

void	setPasteSpecialForcesKeyFrameAtBegAndEnd (bool flag)
	PasteSpecial Structure value. Default value is true. More...

void	setPasteSpecialOffsetKeyFrames (bool flag)
	PasteSpecial Structure value. Default value is false. More...

void	setPasteSpecialReplaceExpressionColumns (bool flag)
	PasteSpecial Structure value. Default value is true. More...

Drawings Section
void	setPasteSpecialDrawingAction (String &mode)
	PasteSpecial Structure value. Default value is "ADD_OR_REMOVE_EXPOSURE". More...

void	setPasteSpecialDrawingFileMode (String &mode)
	PasteSpecial Structure value. Default value is "ALWAYS_CREATE" if "LIBRARY_PASTE_CREATE_NEW_DRAWING" is set, otherwise it is "ONLY_CREATE_IF_DOES_NOT_EXIST". More...

void	setPasteSpecialDrawingAutomaticExtendExposure (bool extendExposure, bool keyFrameMode)
	PasteSpecial Structure value. Default values are extendExposure : false, keyFrameMode: true. More...

void	setPasteSpecialColorPaletteOption (String &mode)
	PasteSpecial Structure value. Default value is "REUSE_PALETTES". More...

Misc section
void	setPasteSpecialCopyScanFiles (bool copy)
	Set to true to copy the scan files associated to the selected drawings. More...

void	setPasteSpecialCopyModelDir (bool copy)
	Set to true to copy the model directory. More...

void	setPasteSpecialTVPreserveName (bool preserve)
	Set to true to keep timed values names intact, even if cloned i.e. Drawing(3). More...

void	setPasteSpecialDefaultCameraName (bool flag)
	Use this when you want the camera in a template to be set as default camera in the target scene. More...

void	setPasteSpecialMatchNodeName (bool flag)
	Use this when you want to paste a template and use the actual node names for matching nodes instead of basic algorithm of composition order. More...

void	setPasteSpecialFullTransfer (bool flag)
	Use this when you want to control the paste of all non animate attributes and all local values of a node. More...

void	setStartFrameSrc (int startFrame)
	When pasting an external template or local content, this functions controls the start frame of the content that will be pasted. More...

void	setNumFramesSrc (int nFrames)
	When pasting an external template or local content, this functions controls the number of frames of the content that will be pasted. More...

CopyOptions *	getCurrentCreateOptions ()
	Returns a copy of the current copy options. More...

PasteOptions *	getCurrentPasteOptions ()
	Returns a copy of the current paste options. More...

DragObject *	copy (StringList &selectionOfNodes, int startFrame, int numFrames, CopyOptions *createOption)
	Create an object that represent a 'copy' of a selection of nodes and a range of frames. More...

bool	paste (DragObject dragObject, StringList &selectionOfNodes, int startFrame, int numFrames, PasteOptions pasteOptions)
	Pastes the drag object as an action template. Must paste over a selection of nodes. No new nodes are created by this action. More...

bool	pasteNewNodes (DragObject dragObject, String &groupWhereToDrop, PasteOptions pasteOptions)

DragObject *	copyFromTemplate (String &filename, int startFrame, int numFrames, CopyOptions *createOption)
	Load a template from the file system onto a drag object, which can then be pasted onto the scene. More...

Detailed Description

The copyPaste JavaScript global object. Copy paste to/from templates. Note: 'Paste Special' options will only take effect if activated beforehand, usePasteSpecial() for more details.

Member Function Documentation

◆ copyFromTemplate

DragObject* copyPaste::copyFromTemplate	(	String &	filename,
		int	startFrame,
		int	numFrames,
		CopyOptions *	createOption
	)

slot

Load a template from the file system onto a drag object, which can then be pasted onto the scene.

Parameters

filename	- the exact filename of the .tpl folder. Need to be the folder, not the .xstage file.
startFrame	- start frames for the data pasted. Starting at 1. However, if 0 is provided, the whole template is copied.
numFrames	- number of frames to paste, up to the maximum number of frames. If 'startFrame' is 0, this parameter is disregarded.
createOption	- options that should be used when doing the code. See CopyOptions for more information about these options.

Returns: Returns a new created copy.

◆ createTemplateFromSelection

String copyPaste::createTemplateFromSelection	(	String	name,
		String &	path
	)

slot

Creates template from the current selection in the scene, using only the current drawing versions.

No template is created when there is nothing selected, when the path is not valid or when there is an IO error.

Parameters

name	: The name of the new template.
path	: The location of the new template.

Returns: Returns the full path of the new template. Will return an empty string if no template file was created.

◆ getCurrentCreateOptions

CopyOptions* copyPaste::getCurrentCreateOptions ( )

slot

Returns a copy of the current copy options.

To be used with copy(). There used to be an API to set these parameters globally, for the next drag&drop

Returns: Returns a copy of the current copy options.

◆ getCurrentPasteOptions

PasteOptions* copyPaste::getCurrentPasteOptions ( )

slot

Returns a copy of the current paste options.

To be used with paste()

Returns: Returns a copy of the current paste options.

◆ paste

bool copyPaste::paste	(	DragObject *	dragObject,
		StringList &	selectionOfNodes,
		int	startFrame,
		int	numFrames,
		PasteOptions *	pasteOptions
	)

slot

Pastes the drag object as an action template. Must paste over a selection of nodes. No new nodes are created by this action.

Parameters

dragObject	: The dragObject to be pasted.
selectionOfNodes	: The list of nodes to be pasted over.
startFrame	: The start frame for the selection. First frame is 1.
numFrames	: The number of frames to paste across.
pasteOptions	: Options that should be used when pasting. See PasteOptions for more information about these options.

Returns: Returns true if successful.

See also: copy() for a code example.

◆ pasteActionTemplateIntoNode

bool copyPaste::pasteActionTemplateIntoNode	(	String &	srcPath,
		String &	nodeName,
		int	insertFrame,
		QScriptValue &	compositionOptions = `QScriptValue()`
	)

slot

Pastes the action template into the scene and excludes nodes that are in the list.

Parameters

srcPath	: The path of the template.
nodeName	: The name of the existing node in which we will insert template.
insertFrame	: The frame at which insert commences.
compositionOptions	: Defines how to handle the selection of nodes onto which to paste. Separately controls to paste of groups, effects and composite nodes when building the selection. Default value: { "groups": true, "effects": true, "composites": false }

Returns: Returns true if successful.

◆ pasteNewNodes

bool copyPaste::pasteNewNodes	(	DragObject *	dragObject,
		String &	groupWhereToDrop,
		PasteOptions *	pasteOptions
	)

slot

Paste an external drag object as new nodes. This is similar to pasting on the node view where new nodes are created (from an external selection).

Parameters

dragObject	- the actual drag object - see copy() or copyFromTemplate() to create this drag object.
groupWhereToDrop	- root group where the new nodes will be created. If empty string is provided, it will paste at the root.
pasteOptions	- paste special options (ie. create keyframes, drawings, new columns, or relink columns,.... - see paste special dialog and PasteOptions).

Returns: Returns true if successful.

◆ pasteTemplateIntoGroup

bool copyPaste::pasteTemplateIntoGroup	(	String &	srcPath,
		String &	groupName,
		int	insertFrame
	)

slot

Pastes the template into a group of the scene.

Parameters

srcPath	: The path of the template.
groupName	: The name of the existing column in which we will insert template.
insertFrame	: The frame at which insert commences.

Returns: Returns true if successful.

◆ pasteTemplateIntoScene

bool copyPaste::pasteTemplateIntoScene	(	String &	templateSrcPath,
		String &	insertColumnName,
		int	insertFrame
	)

slot

Pastes the template into the scene.

Parameters

templateSrcPath	: The path of the template.
insertColumnName	: The name of the existing column in which we will insert template.
insertFrame	: The frame at which insert commences.

Returns: Returns true if successful.

◆ setExtendScene

void copyPaste::setExtendScene ( bool flag )

slot

PasteSpecial Structure value. Default value is false.

Parameters

flag	: The new value.

◆ setNumFramesSrc

void copyPaste::setNumFramesSrc ( int nFrames )

slot

When pasting an external template or local content, this functions controls the number of frames of the content that will be pasted.

The default number of frames is 0, which effectively turn off this override feature and make it paste the entire copied content length. Set this length to anything >0 to override the number of frames pasted.

Warning: This paste option will only take effect after usePasteSpecial() is called with 'true', otherwise the default value will be used.

Parameters

nFrames : The number of frames that the content will be pasted.

◆ setPasteSpecialAddRemoveAngleKeyFrame

void copyPaste::setPasteSpecialAddRemoveAngleKeyFrame ( bool flag )

slot

PasteSpecial Structure value. Default value is true.

Parameters

flag	: The new value.

◆ setPasteSpecialAddRemoveMotionKeyFrame

void copyPaste::setPasteSpecialAddRemoveMotionKeyFrame ( bool flag )

slot

PasteSpecial Structure value. Default value is true.

Parameters

flag	: The new value.

◆ setPasteSpecialAddRemoveScalingKeyFrame

void copyPaste::setPasteSpecialAddRemoveScalingKeyFrame ( bool flag )

slot

PasteSpecial Structure value. Default value is true.

Parameters

flag	: The new value.

◆ setPasteSpecialAddRemoveSkewKeyFrame

void copyPaste::setPasteSpecialAddRemoveSkewKeyFrame ( bool flag )

slot

PasteSpecial Structure value. Default value is true.

Parameters

flag	: The new value.

◆ setPasteSpecialAddRemoveVelocityKeyFrame

void copyPaste::setPasteSpecialAddRemoveVelocityKeyFrame ( bool flag )

slot

PasteSpecial Structure value. Default value is true.

Parameters

flag	: The new value.

◆ setPasteSpecialColorPaletteOption

void copyPaste::setPasteSpecialColorPaletteOption ( String & mode )

slot

PasteSpecial Structure value. Default value is "REUSE_PALETTES".

Warning: This paste option will only take effect after usePasteSpecial() is called with 'true', otherwise the default value will be used.

Parameters

mode

: The Color Palette Option mode, acceptable strings are:

"DO_NOTHING" - Paste does not modify the palette list of the destination element.
"REUSE_PALETTES" - Paste will copy the palette if a file with the same name does not exists at the destination.
"COPY_AND_OVERWRITE_EXISTING_PALETTES" - Paste will overwrite any palette file at the destination.
"COPY_AND_CREATE_NEW_PALETTES" - Paste will not overwrite palette files at the destination, it will create new files with unique names.
"COPY_AND_CREATE_NEW_PALETTES_IN_ELEMENT_FOLDER" - Similar to COPY_AND_CREATE_NEW_PALETTES, but in the destination element directory, instead of the orignal location.
"COPY_PALETTE_AND_MERGE_COLOURS" - Paste will combine the colours of the two palettes (adds unexesting colours to the destination palette).
"COPY_PALETTE_AND_UPDATE_COLOURS" - Paste will update the colours in the destination palettes with the ones from the source palette.
- "LINK_TO_ORIGINAL" - Paste will not copy the palette file, it will instead add/link the original palette to the element's palette list.
"COPY_SCENE_PALETTE_AND_MERGE_COLOURS" - Paste will combine the two palettes and add unexisting colours to the destination palette.
"COPY_SCENE_PALETTE_AND_UPDATE_COLOURS" - Paste will combine the two palette and overwrite any colours in the destination palette.

◆ setPasteSpecialCopyModelDir

void copyPaste::setPasteSpecialCopyModelDir ( bool copy )

slot

Set to true to copy the model directory.

Parameters

copy	: Whether or not to copy the model directory.

◆ setPasteSpecialCopyScanFiles

void copyPaste::setPasteSpecialCopyScanFiles ( bool copy )

slot

Set to true to copy the scan files associated to the selected drawings.

Parameters

copy	: Whether or not to copy the scan files associated to the selected drawings.

◆ setPasteSpecialCreateNewColumn

void copyPaste::setPasteSpecialCreateNewColumn ( bool flag )

slot

PasteSpecial Structure value. Default value is false.

Parameters

flag	: The new value.

◆ setPasteSpecialDefaultCameraName

void copyPaste::setPasteSpecialDefaultCameraName ( bool flag )

slot

Use this when you want the camera in a template to be set as default camera in the target scene.

Note: This is not necessary if there is no camera assigned in the target scene, as the incoming camera will automatically be set as default camera.

Parameters

flag	: Whether or not to set the camera in the template to be set as the default camera in the target scene.

◆ setPasteSpecialDrawingAction

void copyPaste::setPasteSpecialDrawingAction ( String & mode )

slot

PasteSpecial Structure value. Default value is "ADD_OR_REMOVE_EXPOSURE".

Warning: This paste option will only take effect after usePasteSpecial() is called with 'true', otherwise the default value will be used.

Parameters

mode

: The Drawing Action mode, acceptable strings are:

"DO_NOTHING" - The paste operation will not affect the drawings.
"ADD_OR_REMOVE_EXPOSURE" - The paste operation will add the necessary exposure on the destination, replacing any prewvious exposure.
"UPDATE_PIVOT" - The paste operation will only affect the drawing pivots on the destination.

◆ setPasteSpecialDrawingAutomaticExtendExposure

void copyPaste::setPasteSpecialDrawingAutomaticExtendExposure	(	bool	extendExposure,
		bool	keyFrameMode
	)

slot

PasteSpecial Structure value. Default values are extendExposure : false, keyFrameMode: true.

Parameters

extendExposure	: Whether or not to automatically extend the exposure.
keyFrameMode	: Whether or not to enable key frame mode.

◆ setPasteSpecialDrawingFileMode

void copyPaste::setPasteSpecialDrawingFileMode ( String & mode )

slot

PasteSpecial Structure value. Default value is "ALWAYS_CREATE" if "LIBRARY_PASTE_CREATE_NEW_DRAWING" is set, otherwise it is "ONLY_CREATE_IF_DOES_NOT_EXIST".

Warning: This paste option will only take effect after usePasteSpecial() is called with 'true' and the setPasteSpecialDrawingAction() is set to "ADD_OR_REMOVE_EXPOSURE", otherwise the default value will be used.

Parameters

mode

: The Drawing File mode, acceptable strings are:

"NEVER_CREATE" - Only pastes the timing (text) of the drawing (mostly useful for Xsheet pasting).
"ONLY_CREATE_IF_DOES_NOT_EXIST" - Pasted drawings which already exist on that element will only create new exposures of those drawings, otherwise new drawings will be created.
"ALWAYS_CREATE" - Always creates new drawings on the paste destination (it automatically generates unique names).
"ALWAYS_CREATE_AND_VERSION_IF_NECESSARY" - Deprecated
"REPLACE_EXISTING" - Always paste drawings with their original name, if a drawing with that same name already exists on the destination, it will be overwritten.

◆ setPasteSpecialElementTimingColumnMode

void copyPaste::setPasteSpecialElementTimingColumnMode ( String mode )

slot

PasteSpecial Structure value. Default value is "ELEMENT_AS_ELEMENT_AND_TIMING_AS_TIMING".

Sets the paste special elementtiming mode for calls to pasteTemplateIntoScene Warning: This paste option will only take effect after usePasteSpecial() is called with 'true', otherwise the default value will be used.

Parameters

mode

: The Timing Column mode, acceptable strings are:

ELEMENT_AS_ELEMENT_AND_TIMING_AS_TIMING - Paste will create the read node as a timing or an element (for the timing case, it will create a folder under timings subdirectory)
ALL_DRWGS_AS_ELEMENTS - Paste will convert all read timing nodes to element nodes (copying all the files).
ALL_DRWGS_LINKED_THRU_TIMING_COLS - Paste will convert all elements nodes to timing nodes (will not copy the drawings files).

◆ setPasteSpecialForcesKeyFrameAtBegAndEnd

void copyPaste::setPasteSpecialForcesKeyFrameAtBegAndEnd ( bool flag )

slot

PasteSpecial Structure value. Default value is true.

Parameters

flag	: The new value.

◆ setPasteSpecialFullTransfer

void copyPaste::setPasteSpecialFullTransfer ( bool flag )

slot

Use this when you want to control the paste of all non animate attributes and all local values of a node.

The default is true.

Parameters

flag	: Whether or not to control the paste of all non animate attributes and all local values of a node.

◆ setPasteSpecialMatchNodeName

void copyPaste::setPasteSpecialMatchNodeName ( bool flag )

slot

Use this when you want to paste a template and use the actual node names for matching nodes instead of basic algorithm of composition order.

In this mode, it is important to make sure that all nodes of the template are found in the destination's group.

Parameters

flag	: Whether or not to use the actual node names for matching nodes when pasting a template.

◆ setPasteSpecialOffsetKeyFrames

void copyPaste::setPasteSpecialOffsetKeyFrames ( bool flag )

slot

PasteSpecial Structure value. Default value is false.

Parameters

flag	: The new value.

◆ setPasteSpecialReplaceExpressionColumns

void copyPaste::setPasteSpecialReplaceExpressionColumns ( bool flag )

slot

PasteSpecial Structure value. Default value is true.

Parameters

flag	: The new value.

◆ setPasteSpecialTVPreserveName

void copyPaste::setPasteSpecialTVPreserveName ( bool preserve )

slot

Set to true to keep timed values names intact, even if cloned i.e. Drawing(3).

Parameters

preserve : Whether or not to keep timed values names intact.

◆ setStartFrameSrc

void copyPaste::setStartFrameSrc ( int startFrame )

slot

When pasting an external template or local content, this functions controls the start frame of the content that will be pasted.

The default start frame is 1, which means that it will be pasting starting from the first frame of the copied content. Set this to a value >= 1 to specific the frame to use as a starting frame. Warning: This paste option will only take effect after usePasteSpecial() is called with 'true', otherwise the default value will be used.

Parameters

startFrame : The frame to start at when pasting an external template or local content.

◆ useCreateTemplateSpecial

void copyPaste::useCreateTemplateSpecial	(	bool	flag,
		bool	addModellingDir = `true`,
		bool	addScanFiles = `true`,
		bool	includeDefaultCameraName = `true`
	)

slot

Allows 2 extra options in the template creation.

Parameters

flag	: Set that the copy paste manager is in use.
addModellingDir	: Copies the modeling directory into the template.
addScanFiles	: Copies the *.scans that match the drawings.
includeDefaultCameraName	: Deprecated in 7.8. As long as the camera node is in the selection, it will be copied into the template automatically.

◆ usePasteSpecial

void copyPaste::usePasteSpecial ( bool flag )

slot

Enables PasteSpecial.

This is a STATIC structure - once initialized it may be re-used for the duration of the session. By default, it is NOT used until usePasteSpecial(true) is called.

The structure defaults are:

extendScene = false

NODE

createNewColumn = false
elementTimingColumnMode = "ELEMENT_AS_ELEMENT_AND_TIMING_AS_TIMING"

PEG

Add/remove motion KF = true
Add/remove velocity KF = true
Add/remove angle KF = true
Add/remove skew KF = true
Add/remove scaling KF = true
Force keyframes at functions beginning and end = true
Offset keyframes = false
Replace expression columns = true

DRAWING

Drawing action = "ADD_OR_REMOVE_EXPOSURE"

PALETTE

Palette mode = REUSE_PALETTES

SRC FRAMES

Start frame source = 1 : Using start frame of the copied sequenced).
Num frame source = 0 : Using 0 indicate to use the original length of the source.

If Drawing add/remove exposure is set, the following modes are available:

Drawing file mode = "ALWAYS_CREATE" if the preference "LIBRARY_PASTE_CREATE_NEW_DRAWING" is set, otherwise it is ONLY_CREATE_IF_DOES_NOT_EXIST
Automatically extend exposure = false
Drawing as key frame = true ( note, only used if automatic extend exposure = true )

Parameters

flag	: true to enable PasteSpecial.

Public Slots

Misc section

Detailed Description

Member Function Documentation

◆ copyFromTemplate

◆ createTemplateFromSelection

◆ getCurrentCreateOptions

◆ getCurrentPasteOptions

◆ paste

◆ pasteActionTemplateIntoNode

◆ pasteNewNodes

◆ pasteTemplateIntoGroup

◆ pasteTemplateIntoScene

◆ setExtendScene

◆ setNumFramesSrc

◆ setPasteSpecialAddRemoveAngleKeyFrame

◆ setPasteSpecialAddRemoveMotionKeyFrame

◆ setPasteSpecialAddRemoveScalingKeyFrame

◆ setPasteSpecialAddRemoveSkewKeyFrame

◆ setPasteSpecialAddRemoveVelocityKeyFrame

◆ setPasteSpecialColorPaletteOption

◆ setPasteSpecialCopyModelDir

◆ setPasteSpecialCopyScanFiles

◆ setPasteSpecialCreateNewColumn

◆ setPasteSpecialDefaultCameraName

◆ setPasteSpecialDrawingAction

◆ setPasteSpecialDrawingAutomaticExtendExposure

◆ setPasteSpecialDrawingFileMode

◆ setPasteSpecialElementTimingColumnMode

◆ setPasteSpecialForcesKeyFrameAtBegAndEnd

◆ setPasteSpecialFullTransfer

◆ setPasteSpecialMatchNodeName

◆ setPasteSpecialOffsetKeyFrames

◆ setPasteSpecialReplaceExpressionColumns

◆ setPasteSpecialTVPreserveName

◆ setStartFrameSrc

◆ useCreateTemplateSpecial

◆ usePasteSpecial