OMC::Clipboard Class Reference

Detailed Description

Provides copy and paste functionality.

The clipboard object is provided from the scene (OMH::HarmonyScene) and provides access to copy and paste functionality. It is useful for copying content from a scene or templates and reusing it in different locations.

Copying Content

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

clipboard = scene.clipboard                                  #The clipboard object.
selection_handler = scene.selection                          #The selection handler.
selection_handler.nodes.select_all()                         #Select all nodes in the scene.

copy_object = clipboard.copy( selection_handler.nodes.list() )    #Create a copy_object in memory from the selection.
selection_handler.select_none()
new_nodes = clipboard.paste_new_nodes( copy_object, scene.top )   #Paste duplicate nodes into the top-group of the scene.

for node in new_nodes:
  print( "Pasted: %s"%(node.path) )                               #Announce the new node's path
  if node.parent_group().path == scene.top.path:
    node.position.y = node.position.y + 300                         #Move it up, to avoid overlap with existing content

Create a Template

import os
from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

clipboard = scene.clipboard                                  #The clipboard object.
selection_handler = scene.selection                          #The selection handler.
selection_handler.nodes.select_all()                         #Select all nodes in the scene.

copy_object = clipboard.copy( selection_handler.nodes.list() )    #Create a copy_object in memory from the selection.

output_path = os.path.expanduser( "~/Template_Example" )
directory = clipboard.create_template(copy_object, "Template_Example", output_path, False )

if directory and len(path)>0:
  full_path = os.path.join( output_path, directory )
  if os.path.exists(full_path):
    print( "Output a Template: %s"%(full_path) )

else:
  print( "Failed to output a template." )

Public Member Functions
void	paste_template (const QString &templateSrcPath, int insertFrame, const OMC::Column *column=null, const OMH::PasteOptions *options)
	Pastes the template into the scene. More...
void	paste_template_into_group (const QString &srcPath, int insertFrame, const OMC::Group *group, const OMH::PasteOptions *options)
	Pastes the template into a group of the scene. More...
void	paste_action_template (const QString &srcPath, int insertFrame, const OMC::Node *node, const OMH::PasteActionOptions *compositionOptions, const OMH::PasteOptions *options)
	Pastes the action template into the scene and excludes nodes that are in the list. More...
OMH::CopyObject *	copy (const QStringList &nodePaths, int startFrame=1, int numFrames=0, const OMC::CopyOptions *copyOptions=null)
	Create an object that represent a 'copy' of a selection of nodes and a range of frames. More...
void	paste (OMH::CopyObject *copyObject, const QStringList &nodePaths, int startFrame=1, int numFrames=0, const OMH::PasteOptions *pasteOptions=null)
	Pastes the drag object as an action template. Must paste over a selection of nodes. No new nodes are created by this action. More...
std::vector< OMC::Node * >	paste_new_nodes (OMH::CopyObject *copyObject, const OMC::Group *group, OMH::PasteOptions *pasteOptions=null)
OMC::CopyObject *	copy_from_template (QString &filename, int startFrame=1, int numFrames=0, OMC::CopyOptions *copyOptions=null)
	Load a template from the file system onto a copy object, which can then be pasted onto the scene. More...
QString	create_selection_template (const QString &name, const QString &path, const OMC::CopyOptions *copyOptions=null) const
	Creates template from the current selection in the scene, using only the current drawing versions. More...
QString	create_template (OMH::CopyObject *copyObject, const QString &name, const QString &path, bool addDefaultCamera=false) const
	Creates template from the copy object using only the current drawing versions. More...

Member Function Documentation

copy()

OMH::CopyObject* OMC::Clipboard::copy	(	const QStringList &	nodePaths,
		int	startFrame = 1,
		int	numFrames = 0,
		const OMC::CopyOptions *	copyOptions = null
	)

Create an object that represent a 'copy' of a selection of nodes and a range of frames.

Create an object that represent a 'copy' of a selection of nodes and a range of frames. This object can be pasted or saved in the template library. It is practically identical to what the user would copy from a selection of layers and frames in the timeline.

Parameters

nodePaths	: The list of nodes to be copied.
createOption	: Options that should be used when doing the creating the copy. See SCR_CopyOptions for more information about these options.

Returns

Returns a newly created 'drag object' that represent a copy of the selection. The drag object can be saved or pasted back to the scene (using the paste() function)

NULL if unable to create a dragobject.

copy_from_template()

OMC::CopyObject* OMC::Clipboard::copy_from_template	(	QString &	filename,
		int	startFrame = 1,
		int	numFrames = 0,
		OMC::CopyOptions *	copyOptions = null
	)

Load a template from the file system onto a copy 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 SCR_CopyOptions for more information about these options.

Returns

Returns a new created copy.

create_selection_template()

QString OMC::Clipboard::create_selection_template	(	const QString &	name,
		const QString &	path,
		const OMC::CopyOptions *	copyOptions = null
	)		const

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.
copyOptions	: Options to define how the selection is copied when templated.

Returns

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

create_template()

QString OMC::Clipboard::create_template	(	OMH::CopyObject *	copyObject,
		const QString &	name,
		const QString &	path,
		bool	addDefaultCamera = false
	)		const

Creates template from the copy object 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.
addDefaultCamera	: Whether the default camera should be included in the template.

Returns

Returns the directory name of the new template. Will return an empty string if no template file was created.

paste()

void OMC::Clipboard::paste	(	OMH::CopyObject *	copyObject,
		const QStringList &	nodePaths,
		int	startFrame = 1,
		int	numFrames = 0,
		const OMH::PasteOptions *	pasteOptions = null
	)

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

Parameters

copyObject	: 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 SCR_PasteOptions for more information about these options.

paste_action_template()

void OMC::Clipboard::paste_action_template	(	const QString &	srcPath,
		int	insertFrame,
		const OMC::Node *	node,
		const OMH::PasteActionOptions *	compositionOptions,
		const OMH::PasteOptions *	options
	)

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.

paste_new_nodes()

std::vector<OMC::Node*> OMC::Clipboard::paste_new_nodes	(	OMH::CopyObject *	copyObject,
		const OMC::Group *	group,
		OMH::PasteOptions *	pasteOptions = null
	)

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

copyObject	- the actual drag object - see copy() or copyFromTemplate() to create this drag object.
group	- 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 SCR_PasteOptions).

Returns

The pasted nodes.

paste_template()

void OMC::Clipboard::paste_template	(	const QString &	templateSrcPath,
		int	insertFrame,
		const OMC::Column *	column = null,
		const OMH::PasteOptions *	options
	)

Pastes the template into the scene.

Parameters

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

paste_template_into_group()

void OMC::Clipboard::paste_template_into_group	(	const QString &	srcPath,
		int	insertFrame,
		const OMC::Group *	group,
		const OMH::PasteOptions *	options
	)

Pastes the template into a group of the scene.

Parameters

srcPath	: The path of the template.
groupName	: The name of the group node into which the template will be pasted.
insertFrame	: The frame at which insert commences.

Returns

Returns true if successful.

Inheritance diagram for OMC::Clipboard:

Collaboration diagram for OMC::Clipboard: