Detailed Description

The attribute wrapper.

This object wraps a single attribute owned by a node. The Drawing attribute provides generic representation for either an Element Attribute when in Element Mode or a Timing Attribute otherwise.

When in Element Mode (OMC::DrawingAttribute::element_mode == True), the drawing is provided by an element object and is sourced from a folder on disk within the project's element folder.
The Element Attribute uses the attached column (OMC::ElementColumn) to provide an element ID and the timing for the drawings. The Element that is linked to the ElementColumn will provide a list of element drawings sourced from the element's folder. The OMC::ElementColumn then provides the timing of this Element's drawings (OMC::ElementDrawing).
See OMC::ElementAttribute, OMC::ElementColumn, OMC::Element and OMC::ElementDrawing for more information.

When in Timing Mode (OMC::DrawingAttribute::element_mode == Frue), the drawing is provided by a TimingAttribute that provides a location, size, suffix and timing for content sourced externally from the project. This content is not sourced from the project's elements folder, and the timing is used to simply target a different source elsewhere or disk.

Public Member Functions
virtual QString	value (int frame) const
	Get the attribute's value. More...

void	set_localvalue (const QVariant &value)
	Set the attribute's local value. More...

void	set_value (int frame, OMC::ElementDrawing *drawing)
	Set the attribute's value as a drawing value at a given frame. More...

OMC::Node *	node () const
	The node that owns this attributes. More...

virtual bool	unlink ()
	Unlinks a column from the attribute. More...

virtual bool	link (const QVariant &column)
	Links a column to the attribute, making it animate over time. More...

bool	set_text_value (int atFrame, const QString &value)
	Modify an attribute with a text value at a given frame. Change an attribute with a text value applied at a specific frame. This provides similar utility as the Javascript libraries available for the application. More...

QString	get_text_value (int atFrame) const
	Get a text value at a given frame. Retrieve the text value of an attribute at a specific frame. This provides similar utility as the Javascript libraries available for the application. More...

Public Attributes
OMC::Column *	column
	Get and set the column object attached to the the attribute. A column of type 'Drawing' (OMC::DrawingColumn) is expected. More...

QString	column_name
	Get and set the column name attached to the the attribute. More...

QVariant	element
	Provides the element connected to the drawing. More...

QString	drawing_type
	The drawing-type of the attribute. More...

QString	element_name
	The element name of the element connected to the attribute. More...

QString	timing_name
	The timing name of the drawing connected to the attribute. More...

bool	element_mode
	Identifies whether this attribute is in element mode or not. More...

OMC::Attribute *	drawing
	Provides either the element attribute or the custom-name attribute depending on the active mode. More...

OMC::Column *	timing
	Provides either the element attribute or the custom-name attribute depending on the active mode. More...

QString	keyword
	Get the keyword of the attribute. More...

QString	display_name
	Get the display name of the attribute. More...

QString	type_name
	Get the display name of the attribute. More...

QString	full_keyword
	Return the full keyword of the Attribute. More...

bool	dynamic
	Identifies if the attribute is dynamic. More...

bool	linkable
	Identifies if the attribute is linkable and can have a column linked to it. More...

AttributeList *	subattributes
	Get the list of subattributes belonging to the attribute. More...

Member Function Documentation

◆ get_text_value()

QString OMC::Attribute::get_text_value ( int atFrame ) const

inherited

Get a text value at a given frame. Retrieve the text value of an attribute at a specific frame. This provides similar utility as the Javascript libraries available for the application.

Parameters

atFrame - The frame at which to set the attribute.

Returns: Returns the text value of the string at the given frame.

◆ link()

virtual bool OMC::Attribute::link ( const QVariant & column )

virtualinherited

Links a column to the attribute, making it animate over time.

Returns: Returns whether the column has been successfully linked to the attribute.

Links a column to the attribute, if the column is compatible with the attribute type. Also see setting OMC::Column::column with a Column object property.

◆ node()

OMC::Node* OMC::Attribute::node ( ) const

inherited

The node that owns this attributes.

Retrieves the Node that owns this attribute.

Returns: Returns the owning OMC::Node object related to this attribute.

◆ set_localvalue()

void OMC::DrawingAttribute::set_localvalue ( const QVariant & value )

Set the attribute's local value.

The Drawing Attribute does not provide a local value – this method only exists as a macro for OMC::DrawingAttribute::set_value( 1, value )

Parameters

value - the OMC::ElementDrawing or drawing name to which the attribute should be set at frame 1.

◆ set_text_value()

bool OMC::Attribute::set_text_value	(	int	atFrame,
		const QString &	value
	)

inherited

Modify an attribute with a text value at a given frame. Change an attribute with a text value applied at a specific frame. This provides similar utility as the Javascript libraries available for the application.

Parameters

atFrame	- The frame at which to set the attribute.
value	- The new value of the attribute.

Returns: Returns whether the attribute has been successfully changed.

◆ set_value()

void OMC::DrawingAttribute::set_value	(	int	frame,
		OMC::ElementDrawing *	drawing
	)

Set the attribute's value as a drawing value at a given frame.

Sets the value of the attribute to the provided drawing value at the given frame.

Parameters

frame	- the frame at which the attribute is set.
value	- the OMC::ElementDrawing or drawing name to which the attribute should be set.

Set a Drawing Value at a Frame

import random
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.
node = scene.nodes["Top/Drawing"]                            #Find the Drawing node.
drawing_attribute_keyword = "DRAWING"                        #The path to a double attribute
attribute = node.attributes[drawing_attribute_keyword]       #Get the attribute by name
if attribute:
  at_frame = 1
  current_value = attribute.value( at_frame )                #Get the attribute's value.
  #Show the current localvalue of the attribute.
  print( "CURRENT VALUE AT %s : %s"%( at_frame, current_value ) )
  element = attribute.element                                #The element associated with the drawing
  possible_drawings = element.drawings.list()                #Provides a list of available drawings for this element.
  new_value = random.choice( possible_drawings )
  attribute.set_value( at_frame, new_value )                                                      #Set the attribute's local value to the new value
  new_value = attribute.value( at_frame )                                                         #Get the attribute's new localvalue, to check it for debug/example purposes
  print( "NEW VALUE AT %s : %s"%( at_frame, new_value ) )
else:
  print( "Unable to find attribute by keyword: %s"%(drawing_attribute_keyword) )

◆ unlink()

virtual bool OMC::Attribute::unlink ( )

virtualinherited

Unlinks a column from the attribute.

Returns: Returns whether the column has been successfully removed from the attribute.

Unlinks any column from the attribute.
Also see OMC::Column::column with property None.

node.attribute["attrbKeyword"].unlink()
#Same as:
node.attribute["attrbKeyword"].column = None

◆ value()

virtual QString OMC::DrawingAttribute::value ( int frame ) const

virtual

Get the attribute's value.

Get the attribute's value as a string representing a drawing's name at a given frame.

Provides the value as a string that represents a drawing's name at a given frame.

Retrieve a Drawing Name at a Frame

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.
node = scene.nodes["Top/Drawing"]                            #Find the Drawing node.
drawing_attribute_keyword = "DRAWING"                        #The path to a double attribute
attribute = node.attributes[drawing_attribute_keyword]       #Get the attribute by name
if attribute:
  at_frame = 1
  current_value = attribute.value(at_frame)                       #Get the attribute's value at frame 1
  #Show the value of the attribute.
  print( "VALUE AT FRAME %s : %s"%( at_frame, current_value ) )
else:
  print( "Unable to find attribute by keyword: %s"%(drawing_attribute_keyword) )

Member Data Documentation

◆ column

OMC::DrawingAttribute::column

Get and set the column object attached to the the attribute. A column of type 'Drawing' (OMC::DrawingColumn) is expected.

Get the Column Associated with a Drawing Attribute

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.
node = scene.nodes["Top/Drawing"]                            #Find the Drawing node.
drawing_attribute_keyword = "DRAWING"                        #The path to a double attribute
attribute = node.attributes[drawing_attribute_keyword]       #Get the attribute by name
if attribute and attribute.column:
  print( "Found a Column: %s "attribute.column.name )  
else:
  print( "Unable to find attribute by keyword: %s"%(drawing_attribute_keyword) )

Set the Column Associated with a Drawing Attribute

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.
node = scene.nodes["Top/Drawing"]                            #Find the Drawing node.
drawing_attribute_keyword = "DRAWING"                        #The path to a double attribute
attribute = node.attributes[drawing_attribute_keyword]       #Get the attribute by name
if attribute and attribute.column:
  #Create a new Drawing Column
  int_idx = 0
  while True:   #This will loop until a valid column name is available. We could check, but the error is also acceptable if caught.
    try:
      new_column = scene.columns.create( "DRAWING", "NEWDRAWING_%03d"%(int_idx), { "scanType" : "COLOR", "fieldChart" : 12, "pixmapFormat" : "SCAN", "vectorType" : "TVG", "createNode" : False } )
      break
    except:   #Increment if we didn't create a proper drawing column, we assume its due to a bad column name.
      int_idx = int_idx + 1
  attribute.column = new_column
  print( "Set the column to : %s "%(attribute.column.name) ) 
else:
  print( "Unable to find attribute by keyword: %s"%(drawing_attribute_keyword) )

◆ column_name

QString OMC::DrawingAttribute::column_name

readwrite

Get and set the column name attached to the the attribute.

Similar to OMC::DrawingAttribute::column – sets the column attached to the drawing attribute with a string corresponding to a OMC::DrawingColumn name.
See OMC::DrawingAttribute::column for more information.

◆ display_name

QString OMC::Attribute::display_name

readinherited

Get the display name of the attribute.

Provides the display name of the attribute. The display name is read only, and is the name of the attribute provided within the GUI to the user.

◆ drawing

OMC::DrawingAttribute::drawing

Provides either the element attribute or the custom-name attribute depending on the active mode.

The drawing source can be provided from a different subattribute depending on the element attribute's mode. This property provides the corresponding attribute given the element's current settings.

◆ drawing_type

QString OMC::DrawingAttribute::drawing_type

read

The drawing-type of the attribute.

A read only property that provides the drawing-type as a string.

◆ dynamic

bool OMC::Attribute::dynamic

readinherited

Identifies if the attribute is dynamic.

Dynamic attributes are those that are created with scripted access to an attribute and are created dynamically and uniquely for that node. These dynamic attributes are not necessarily standard for the node-type, and can be added or removed from the node on-demand.
See OMC::AttributeList::create_dynamic_attr for more information.

Create a new Double Dynamic Attribute

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.
node_path = "Top/Node"
node = scene.nodes[ node_path ]
if node:
  attrbs = node.attributes
  created_attribute = attrbs.create_dynamic_attr( "DOUBLE", "DYNAMIC_NAME", "DYNAMIC_DISPLAY", True )
  if created_attribute:
    if created_attribute.dynamic:                            #Expected to be true, since we just created it.
      print( "Created Dynamic Attribute: %s"%(created_attribute.full_keyword) )
      created_attribute.set_value(1, 10, False)
  else:
    print( "Failed to create attribute." )
else:
  print( "Node does not exist: %s"%(node_path) )

◆ element

QVariant OMC::DrawingAttribute::element

read

Provides the element connected to the drawing.

A DrawingAttribute has an element associated with it (generally provided via the column). This element property is provided as an OMC::Element object and provides access to the OMC::ElementDrawing and OMC::ElementDrawingList; allowing one to create, modify and remove drawings associated with that element.

List All Drawings Available

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.
node = scene.nodes["Top/Drawing"]                            #Find the Drawing node.
drawing_attribute_keyword = "DRAWING"                        #The path to a double attribute
attribute = node.attributes[drawing_attribute_keyword]       #Get the attribute by name
if attribute:
  element = attribute.element                                #The element associated with the drawing
  if element:
    print( "Element ID : %s"%(element.id) )
    element_drawings = element.drawings
    for element_drawing in element_drawings:
      print( "Drawing Name : %s"%(element_drawing.name) )
else:
  print( "Unable to find attribute by keyword: %s"%(drawing_attribute_keyword) )

◆ element_mode

bool OMC::DrawingAttribute::element_mode

readwrite

Identifies whether this attribute is in element mode or not.

When in Element Mode, the drawings will be sourced from the attached OMC::ElementColumn and its element ID. Otherwise, it is in timing mode and the drawings will be sourced from the attached OMC::TimingColumn and a reference elsewhere on disk.

◆ element_name

QString OMC::DrawingAttribute::element_name

read

The element name of the element connected to the attribute.

The element associated with the DrawingAttribute (often provided via the OMC::Column attached to the attribute) has both a unique ID and a name. This element name is available either through the element property (OMC::DrawingAttribute::element::name) or with this property.

List All Drawings Available

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.
node = scene.nodes["Top/Drawing"]                            #Find the Drawing node.
drawing_attribute_keyword = "DRAWING"                        #The path to a double attribute
attribute = node.attributes[drawing_attribute_keyword]       #Get the attribute by name
if attribute:
  print( "Element Name : %s"%(attribute.element_name) )
  
  #Equivalent to . . . 
  element = attribute.element                                #The element associated with the drawing
  if element:
    print( "Element Name [from Object] : %s"%(element.name) )
else:
  print( "Unable to find attribute by keyword: %s"%(drawing_attribute_keyword) )

◆ full_keyword

QString OMC::Attribute::full_keyword

readinherited

Return the full keyword of the Attribute.

All columns can be referenced by their full keyword as this provides the full path to the given attribute on a Node.

Note: The full_keyword is useful when referencing an attribute from a node, even if that attribute is a subattribute of another. Notice in the example below, that only the full keyword is printed, which provides the path to the attribute from the base of the node's attribute list (see OMC::AttributeList::operator[ QString& keyword ]).

Get the Keyword of All Attributes on 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                                           #Get the top scene in the project.
node_path = "Top/Node"
node = scene.nodes[ node_path ]
def attrb_keywords( attrblist, depth ):
  for attrb in attrblist:
    print( "%s %s"%( "  "*depth, attrb.full_keyword ) )      #Only printing the keyword of the attribute. Note, subattributes will only print their basename, and not their parent's in a path.
    if attrb.subattributes:
      attrb_keywords( attrb.subattributes, depth+1 )         #If we hit something with subattributes, print those too!
if node:
  attrb_keywords( node.attributes, 0 )
else:
  print( "Unable to find node: %s"%(node_path) )

◆ keyword

QString OMC::Attribute::keyword

readinherited

Get the keyword of the attribute.

All columns are referenced by their keyword when relative to a given parent object. Otherwise, they are referenced by their full_keyword (OMC::Column::full_keyword) property – which contains the full path to that attribute on a given Node.

Note: The keyword is useful when relative to a given parent, but the full_keyword will provide the absolute path of the attribute. Notice in the example below, that only the relative keyword is printed.

Get the Keyword of All Attributes on 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                                           #Get the top scene in the project.
node_path = "Top/Node"
node = scene.nodes[ node_path ]
def attrb_keywords( attrblist, depth ):
  for attrb in attrblist:
    print( "%s %s"%( "  "*depth, attrb.keyword ) )           #Only printing the keyword of the attribute. Note, subattributes will only print their basename, and not their parent's in a path.
    
    if attrb.subattributes: 
      attrb_keywords( attrb.subattributes, depth+1 )         #If we hit something with subattributes, print those too!
if node:
  attrb_keywords( node.attributes, 0 )
 
else:
  print( "Unable to find node: %s"%(node_path) )

◆ linkable

bool OMC::Attribute::linkable

readinherited

Identifies if the attribute is linkable and can have a column linked to it.

Only some attributes are animateable and accept a column. If a column is set on a non-linkable attribute, an error is thrown.
See OMC::Attribute::column for an example.

◆ subattributes

OMC::Attribute::subattributes

inherited

Get the list of subattributes belonging to the attribute.

Provides the subattribute list (OMC::AttributeList) for this attribute, if one is available. Only certain attribute-types are considered complex, and contain subattributes.

Identify if an Attribute has Subattributes

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.
node_path = "Top/Node"
node = scene.nodes[ node_path ]
if node:
  for attrbs in node.attributes:
    if attrbs.subattributes:
      print( "Attrb %s has %s subattributes."%(attrbs.full_keyword, len(attrbs.subattributes) ) )
    else:
      print( "Attrb %s has no subattributes."%(attrbs.full_keyword) )
else:
  print( "Unable to find node: %s"%(node_path) )

See OMC::Attribute::column for more examples.

◆ timing

OMC::DrawingAttribute::timing

Provides either the element attribute or the custom-name attribute depending on the active mode.

The timing and exposure of the drawings can be provided from a different subattribute depending on the element attribute's mode. This property provides the corresponding attribute given the element's current settings.

◆ timing_name

QString OMC::DrawingAttribute::timing_name

read

The timing name of the drawing connected to the attribute.

A read-only property that provides the timing name of the attribute. Different DrawingAttribute settings can result in different timing sources.

◆ type_name

OMC::Attribute::type_name

inherited

Get the display name of the attribute.

Provides the type-name of the attribute. Different attribute-types provide different information to the node and also require different column-types when linked (if linkable).

Note: Different subclasses of the OMC::Attribute object are provided for different attribute types. These different subclasses provode specific utilties for that attribute-type. See OMC::BoolAttribute, OMC::ColourAttribute, OMC::DoubleAttribute, OMC::DrawingAttribute, OMC::ElementAttribute, OMC::EnumAttribute, OMC::IntAttribute, OMC::Position2DAttribute, OMC::Position3DAttribute, OMC::TextAttribute and OMC::TimingAttribute.

See OMC::Attribute::column for an example.

Inheritance diagram for OMC::DrawingAttribute:

[legend]

Collaboration diagram for OMC::DrawingAttribute:

[legend]

Detailed Description

Public Member Functions

Public Attributes

Member Function Documentation

◆ get_text_value()

◆ link()

◆ node()

◆ set_localvalue()

◆ set_text_value()

◆ set_value()

◆ unlink()

◆ value()

Member Data Documentation

◆ column

◆ column_name

◆ display_name

◆ drawing

◆ drawing_type

◆ dynamic

◆ element

◆ element_mode

◆ element_name

◆ full_keyword

◆ keyword

◆ linkable

◆ subattributes

◆ timing

◆ timing_name

◆ type_name