OMC::NodeList Class Reference

Detailed Description

A class representing a list of nodes, providing utilities to modify, filter, and search the list.

The Node List is an iterable object, with indexed-access. This means it can be iterated with a for-loop, provides a length/size method and can be accessed with a list index.

Iterable Object-Type

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.
nodes = scene.nodes                                          #Get the node list of the scene.

#Iterating on the node list with a for-loop
for node in node:                                            #For loop on the node list.
  print( "Node : %s"%(node.path) )                           

---

Iterating with Index Accessor

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.
nodes = scene.nodes                                          #Get the node list of the scene.

node_size = len(nodes)                                       #Gets the size of the node list. This is a standard method for iterable list object-types.

#Iterating on the node list with a ranged for-loop
for node_idx in range(node_size):                            #For loop on a range based on node list's size.
  node = nodes[node_idx]                                     #Get the node from the node_idx currently being looped.
  print( "Node : %s - %s"%(node_idx, node.path) ) 

---

The Node List also allows for name/path accessing. This is useful when accessing nodes based on the absolute path in the scene, or when relative to a group. If this nodelist is provided by the scene from OMC::Scene::nodes, the paths are not relative to any specific groups and needs to be provided as an absolute path name. If this nodelist is provided by a group, even the 'Top' group of the scene, the paths are relative to that group and can be provided with a name relative to that group's path.

Accessing a Node by its Path:

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.
nodes = scene.nodes                                          #Get the node list of the scene.

desired_node = nodes["Top/Peg"]                              #Find the node by the requested path : "Top/Peg"
if desired_node:
  print( "Found Node: %s"%(desired_node) )
else:
  print( "No Node found by the requested name." )

Public Member Functions
virtual size_t	size () const override
	Provides the list's size. More...
virtual bool	contains (const QString &name) const
	Checks if the provided node name exists in the node-list. More...
virtual std::vector< NODE_OBJ >	list () const override
	Converts the dynamic list to a concrete list of nodes. More...
virtual OMC::Node *	create (const QString &type, const QString &name)
virtual OMC::Node *	create (const QString &type, const QString &path, const QString &name)
QVariant	move (OMC::Node *node, int x=0, int y=0)
void	remove (const QVariant &path, bool delElems=false, bool delTVs=false)
	Removes the node at the path from the list (group, scene, ect)

Protected Member Functions
void	validate () const override

Member Function Documentation

contains()

virtual bool OMC::NodeList::contains ( const QString &  name ) const

virtual

Checks if the provided node name exists in the node-list.

Checks the list for the provided item. Will return true if the list contains that item. This is also available via the Python built-in check for list object [ contained = object in list ].

create() [1/2]

virtual OMC::Node* OMC::NodeList::create ( const QString &  type, const QString &  name  )

virtual

Creates a new node in the scene.

Parameters

name	- The required name of the node to be added to the group – if the name is already in use, it will be incremented with an integer.
type	- The type of the node.

Returns

The Node object that was added to the group or scene.

/anchor node_create1 Creates a node (represented by a OMC::Node object) in the scene or group, depending on the source of this nodelist. When creating a node in the scene's node list (OMC::Scene::nodes), the name expects an absolute path for the node, containing any group in which the node should be created. When creating a node in the group's node list, the name can be a name within that group, a relative path to the group or an abosolute path.

Creating a Node:

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

#Create a node in the scene list.
scene_node_list = scene.nodes

new_group = scene_node_list.create( "GROUP", "GROUP001" )
print( "NEW SCENE-LIST GROUP: %s"%(new_group.path) )


#Create a node in the group list, using the newly created Group.
group_node_list = new_group.nodes

new_node1 = group_node_list.create( "PEG", "PEG001" )       #Note, since this node is created from the new group's object, it will be created in a path relative to it.
print( "NEW GROUP-LIST NODE 1: %s"%(new_node1.path) )

new_node2 = group_node_list.create( "PEG", "Top/GROUP001/PEG002" )  #This is also acceptable, since the absolute path is within the group thats being created.
print( "NEW GROUP-LIST NODE 2: %s"%(new_node2.path) )

try:
  new_node3 = group_node_list.create( "PEG", "Top/DIFFERENTGROUP/PEG002" )  #This is not acceptable, as the different group isn't the same as the generating group on which this was run.
except:
  print( "This should fail! Since the group doesn't have access to the path as noted." )

create() [2/2]

virtual OMC::Node* OMC::NodeList::create ( const QString &  type, const QString &  path, const QString &  name  )

virtual

Creates a new node in the scene.

Parameters

type	- The type of the node.
path	- The group at which the node is added.
name	- The required name of the node to be added to the group – if the name is already in use, it will be incremented with an integer.

Returns

The Node object that was added to the greoup.

Similar to the OMC::Node::create without path access – this is an overloaded method that provides a utility for providing a separate path and name.
See related method.

list()

virtual std::vector<NODE_OBJ> OMC::NodeList::list ( ) const

overridevirtual

Converts the dynamic list to a concrete list of nodes.

By default, the nodelist object is a dynamic list-type. This means that the object does not contain a persistent list, but behaves dynamically when a node is requested from it. Sometimes, a static list is preferred and this method will generate a static list of OMC::Node objects. Note, although the list is static, the objects within the list remain dynamic and refer to a node within the project.

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

dynamic_nodelist = scene.nodes                               #The dynamic node list.
static_nodelist  = scene.nodes.list()                        #Covnerted the dynamic node list to a static list.

top = scene.top                                              #The top group.
new_node_count = 5

for n in range(new_node_count):
  top.nodes.create( "PEG", "NewPeg_%05d"%(n) )

print( "Dynamic Size: %s"%(len(dynamic_nodelist)) )          #Expecting that the dynamic node list contains 5 more pegs.
print( "Static Size: %s"%(len(static_nodelist)) )

#Another handy factor of the static list is Python's list comprehension and iteration:
static_nodelist = scene.nodes.list()                         #Update the static list.

for node in static_nodelist[::2]:
  print( "Every second node: %s"%(node.path) )

for node in static_nodelist[::-1]:
  print( "Nodes backwards: %s"%(node.path) )

move()

QVariant OMC::NodeList::move	(	OMC::Node *	node,
		int	x = 0,
		int	y = 0
	)

Creates new node[s] in the scene.

Parameters

details

- A JSON style object in form : [ { "group": "path", "name": "nameOfNode", "type":"typeName", "x":0, "y":0 } ].

Returns

The Node object that was added to the greoup.

Moves an existing node to the group. Fails with an error if the move is not possible.

Parameters

path	- The path of the node to move into this group.
x	- The x coordinate of the node in the node view.
y	- The y coordinate of the node in the node view.

This is used primarily in group node lists and is useful for moving a node from one group into another group.

Moving a Node into a Group

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

#Create a node in the scene list.
scene_node_list = scene.nodes

new_group = scene_node_list.create( "GROUP", "GROUP001" )
print( "NEW SCENE-LIST GROUP: %s"%(new_group.path) )

new_node1 = scene_node_list.create( "PEG", "PEG001" )       #This is created in the TOP group, as its the default location for the Scene's nodelist.
print( "NEW GROUP-LIST NODE 1: %s"%(new_node1.path) )

#Now, lets move the newly created node into the new group.
target_group_list = new_group.nodes                         #The new group's node list, this is the target for new_node1.

new_node2 = target_group_list.move( new_node1 )
print( "The node has been moved: %s"%(new_node2) )        

try:
  print( "This will fail: %s"%(new_node1.path) )            #Note, since the original node object was moved -- it no longer retains the link to the node in the scene.
except:                                                     #The move method will provide a new node object that links to the node[s] in the new group.
  print( "As expected, new_node1 no longer exists and is not valid, use new_node2 instead." )

size()

virtual size_t OMC::NodeList::size ( ) const

overridevirtual

Provides the list's size.

The size of the list is available from the size-method, but also available from the built-in utilities in Python [ len( Object ), Object.__len__ ]
See referencing from an list index.

Inheritance diagram for OMC::NodeList:

Collaboration diagram for OMC::NodeList: