Base class for objects that have animatable/storable properties.

More...

Inherits :

• QObject
  • DzBase

Inherited By : DzBackdrop, bonebinding_dz, bulgebinding_dz, geometryregion_dz, iraypropertyholder_dz, legacyalternategeometry_dz, legacyjoint_dz, legacyjointparam_dz, DzMaterial, DzModifier, DzNode, DzObject, shaderbrick_dz, shape_dz, simulationsettingsprovider_dz and weightmap_dz

Classes derived from DzElement may have any number of properties (objects derived from DzProperty). Those properties may be added and removed at runtime and may be specified as animatable or not. There are several types of properties that have been supplied with the Studio SDK. Property names must be unique within an element. A variety of methods are provided to allow easy traversal and/or searching of the properties list for an object.

Methods are provided to clear animation data on all properties of an object either over a range or over all time.

DzElement takes ownership of all properties added via addProperty(). Subclasses should not attempt to delete properties that have been added to the element.

DzElement also handles saving and loading of all properties. When DzElement loads a property from a file, it will delete any existing property of the same name and replace it with the new property read in - subclasses are responsible for updating any local references to properties whenever a file is loaded. The easiest and most reliable way to do this is for the subclass to write out and read back in any local pointers it maintains to properties. Another approach would be for the subclass to reimplement the postLoadFile() function and update its references by calling findProperty() to lookup the properties by name.

---

Number : elementID

Holds the number used to uniquely identify this element in the scene. (Read Only)

Since:

• 4.6.4.13

---

DzError : addDataItem( DzElementData item )

Hang a new custom data item off of this element. Data items will be deleted when this element is deleted, so ownership of the data item is transferred to the element after this call. Do not attempt to delete the data item yourself unless you call removeDataItem() first.

Parameter(s):

• item - The data item to attach to this element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• removeDataItem()

---

DzError : addPrivateProperty( DzProperty prop )

Add a new private property that will be available for connections or direct editing.

Parameter(s):

• prop - The property to add to the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• removeProperty()

---

DzError : addProperty( DzProperty prop )

Add a new property. Adds a new property that will be available for connections or direct editing.

Parameter(s):

• prop - The property to add to the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• removeProperty()

---

void : beginEdit()

Begins an editing operation for this element - DzProperty::beginEdit() will be called for all properties belonging to this element.

---

void : cancelEdit()

Cancels an editing operation for this element - DzProperty::cancelEdit() will be called for all properties belonging to this element.

---

void : clearAllAnimData()

Removes all animation keys on this object.

---

void : clearAnimData( DzTimeRange range )

Clear animation keys in the currently active animation layer. Removes animation data on all animatible properties owned by this element over the given range.

Parameter(s):

• range - The range of time over which keys will be removed.

---

void : copyFrom( DzElement source )

Matches the properties on this element to properties on the given element by name, and then copies the values of matching properties on source to the properties on this element.

Parameter(s):

• source - The element that this element should copy property values from.

---

elementclipboard_dz : copyToClipboard( Array contentTypes=[] )

Copies the property values of the element to a 'clipboard' so that they may be saved and applied (copied) to another element - or to the same element.

Parameter(s):

• contentTypes - A list of the contentTypes that should be included in the copy. An empty list will copy all property values.

Return Value:

• The 'clipboard' which holds a copy of the current element's property values. These values are a snapshot of the current state of the element, and will remain unchanged even if the element is changed or deleted. The caller is responsible for deleting this object.

---

DzError : deleteDataItem( DzElementData item )

Remove the the data item from this element and deletes it. Pointer is invalid after this call if DZ_NO_ERROR is returned.

Parameter(s):

• item - The data item to remove.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addDataItem()

---

DzElementData : findDataItem( String dataName )

Retrieve the user data item with the given ID, if one with that ID is attached to this element.

Parameter(s):

• dataName - Unique ID to use in looking up the user data item.

Return Value:

• The corresponding item if found, NULL if no match.

---

Number : findDataItemIndex( DzElementData item )

Searches for the first data item index.

Parameter(s):

• item - The data item to find.

Return Value:

• The index of the data item.

---

DzProperty : findMatchingProperty( DzProperty srcProp )

Locate a matching property.

Parameter(s):

• srcProp - The property to search for a match.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findPrivateProperty( String name )

Locate a property by name.

Parameter(s):

• name - The name of the property to search for.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findPrivateProperty( String name, Boolean caseSensitive )

Locate a property by name.

Parameter(s):

• name - The name of the property to search for.
• caseSensitive - Whether or not the search should be case sensitive.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findPrivatePropertyByLabel( String label )

Locate a property by label.

Parameter(s):

• label - The label of the property to search for.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findPrivatePropertyByLabel( String label, Boolean caseSensitive )

Locate a property by label.

Parameter(s):

• label - The label of the property to search for.
• caseSensitive - Whether or not the search should be case sensitive.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findProperty( String name )

Locate a property by name.

Parameter(s):

• name - The name of the property to search for.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findProperty( String name, Boolean caseSensitive )

Locate a property by name.

Parameter(s):

• name - The name of the property to search for.
• caseSensitive - Whether or not the search should be case sensitive.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findPropertyByLabel( String label )

Locate a property by label.

Parameter(s):

• label - The label of the property to search for.

Return Value:

• The property, or NULL if not found.

---

DzProperty : findPropertyByLabel( String label, Boolean caseSensitive )

Locate a property by label.

Parameter(s):

• label - The label of the property to search for.
• caseSensitive - Whether or not the search should be case sensitive.

Return Value:

• The property, or NULL if not found.

---

void : finishEdit()

finishes an editing operation for this element - DzProperty::finishEdit() will be called for all properties belonging to this element.

---

void : getAttributes( DzSettings settings )

Populates the given settings object with the attributes of this element. If this settings object is not empty the save filters will save out this settings information in the preset.

Parameter(s):

• settings - The settings object to put the information in.

See Also:

• setAttributes()

---

DzElementData : getDataItem( Number index )

Parameter(s):

• index - The index of the data item to return.

Return Value:

• The data item for this element at the given index.

---

Array : getDataItemList()

Return Value:

• A list of the data items attached to this element.

---

DzElement : getElementChild( Number which )

Parameter(s):

• which - The index of the child element to return.

Return Value:

• The child of this element at the given index.

---

DzElement : getElementParent()

Return Value:

• The element that is the parent of this element. Null if the element has no parent.

---

String : getLabel()

Return Value:

• The user-defined interface label for this element.

---

DzScript : getLoadScript()

Return Value:

• The script that is executed when this element is loaded from a file.

---

Number : getNumDataItems()

Return Value:

• The number of user data items attached to this element.

---

Number : getNumElementChildren()

Return Value:

• The number of children this element has.

---

Number : getNumPrivateProperties()

Return Value:

• The number of private properties currently owned by this element.

---

Number : getNumProperties()

Return Value:

• The number of properties currently owned by this element.

---

DzProperty : getPrivateProperty( Number index )

Get a property from this element's property list.

Parameter(s):

• i - The index of the property to get.

Return Value:

• The property at the given index.

---

DzPropertyGroupTree : getPrivatePropertyGroups()

Return Value:

• The property group tree for private properties owned by this element. If this element does not manage its own property grouping, the tree that is returned will be the tree of the element that manages the property groups for this element.

---

Array : getPrivatePropertyList()

Return Value:

• A list of all the private properties on this element.

---

DzProperty : getProperty( Number index )

Get a property from this element's property list.

Parameter(s):

• i - The index of the property to get.

Return Value:

• The property at the given index.

---

DzPropertyGroupTree : getPropertyGroups()

Return Value:

• The property group tree for properties owned by this element. If this element does not manage its own property grouping, the tree that is returned will be the tree of the element that manages the property groups for this element.

---

Array : getPropertyList()

Return Value:

• A list of all the properties on this element.

---

String : getUniqueDataItemName( String dataName )

Parameter(s):

• dataName - The name of the data item to make unique.

Return Value:

• The original value if dataName is already unique, otherwise a unique name.

Since:

• 4.9.3.117

---

String : getUniquePrivatePropertyName( String name )

Parameter(s):

• name - The private property name to make unique.

Return Value:

• The original value if name is already unique, otherwise a unique private property name.

Since:

• 4.9.3.117

---

String : getUniquePropertyName( String name )

Parameter(s):

• name - The property name to make unique.

Return Value:

• The original value if name is already unique, otherwise a unique property name.

Since:

• 4.9.3.117

---

Boolean : inEdit()

Return Value:

• true if the element is in an editing operation, otherwise false.

See Also:

• beginEdit(), finishEdit(), cancelEdit()

---

DzError : insertPrivateProperty( Number index, DzProperty prop )

Adds a new property that will be available for connections or direct editing.

Parameter(s):

• index - The location in the list to insert the new property.
• prop - The property to add to the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• removeProperty()

---

DzError : insertProperty( Number index, DzProperty prop )

Add a new property. Adds a new property that will be available for connections or direct editing.

Parameter(s):

• index - The index in the properties list to insert the property.
• prop - The property to insert in the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addProperty(), removeProperty()

---

DzError : moveDataItemToIndex( DzElementData item, Number index )

Moves a data item to a new index.

Parameter(s):

• item - The data item to move.
• newIndex - The new index of the item.

Return Value:

• An error code.

---

DzError : movePrivateProperty( DzProperty prop, DzElement element )

Moves the given property from this element to newElement, if it can be removed. Properties can be specified as non-removable (e.g. the rotation channels of the DzNode class). Doing so makes it impossible to move that property to another element.

Parameter(s):

• prop - The property to remove from the element. If prop is not a user property, it returns DZ_ILLEGAL_ARGUMENT_ERROR. Note: This is also the return code for a null pointer. Passing a null pointer generates a log message, whereas passing a non-user property does not.
• newElement - The element that prop should be moved to.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addProperty()

---

DzError : moveProperty( DzProperty prop, DzElement element )

Moves the given property from this element to newElement, if it can be removed. Properties can be specified as non-removable (e.g. the rotation channels of the DzNode class). Doing so makes it impossible to move that property to another element.

Parameter(s):

• prop - The property to remove from the element. If prop is not a user property, it returns DZ_ILLEGAL_ARGUMENT_ERROR. Note: This is also the return code for a null pointer. Passing a null pointer generates a log message, whereas passing a non-user property does not.
• newElement - The element that prop should be moved to.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addProperty()

---

DzError : removeDataItem( DzElementData item )

Remove the data item from this element.

Parameter(s):

• item - The data item to remove.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addDataItem()

---

DzError : removePrivateProperty( DzProperty prop )

Removes the given property, if it can be removed. Properties can be specified as non-removable (e.g. the rotation channels of the DzNode class). Doing so makes it impossible to remove that property from the object.

Parameter(s):

• prop - The property to remove from the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addProperty()

---

DzError : removePrivateProperty( String name )

Attempts to remove the named property. Fails if the property could not be found or could not be removed.

Parameter(s):

• name - The name of the property to search for and remove if it is found.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addProperty()

---

DzError : removeProperty( DzProperty prop )

Removes the given property, if it can be removed. Properties can be specified as non-removable (e.g. the rotation channels of the DzNode class). Doing so makes it impossible to remove that property from the object.

Parameter(s):

• prop - The property to remove from the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addProperty()

---

DzError : removeProperty( String name )

Attempts to remove the named property. Fails if the property could not be found or could not be removed.

Parameter(s):

• name - The name of the property to search for and remove if it is found.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addProperty()

---

DzElement : setAttributes( DzSettings settings )

Sets attributes in the handed in settings and returns a pointer to an element set by these settings. The element returned may not be a new element or null if the settings are not correct. Default implementation returns this with no changes.

Parameter(s):

• settings - The settings object containing the information.

Return Value:

• A new element, or this element if no changes were made. The caller is responsible for cleaning up the memory of the return element if it is not this.

---

DzError : setLabel( String name )

Set the user-defined label that is displayed in the interface for this object.

Parameter(s):

• name - The new label for the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an error code.

---

void : setLoadScript( DzScript script )

Sets the script that will be executed when this element is loaded from a file.

Parameter(s):

• script - The script that will be saved with this element and executed when it is loaded from file. The element takes ownership.

---

void : setName( String name )

Set the internal name of this object.

Parameter(s):

• name - The name to assign to this element.

---

Boolean : shouldSortOnLoad()

Return Value:

• true if this element should have its property groups and properties sorted after being created on load, otherwise false.

---

void : update()

Called to update any cached or display data for this object.

---

void : labelChanged( String newLabel )

Signature:“labelChanged(const QString&)”

Emitted when this object's label is changed.

Parameter(s):

• newLabel - The new label of the element.

---

void : parentChanged()

Signature:“parentChanged()”

Emitted when this element's parent is changed.

---

void : privatePropertyAdded( DzProperty prop )

Signature:“privatePropertyAdded(DzProperty*)”

Emitted when a private property is added to this element.

Parameter(s):

• prop - The property just added.

---

void : privatePropertyListChanged()

Signature:“privatePropertyListChanged()”

Emitted when a private property is added to or removed from this element.

---

void : privatePropertyListInTreeChanged()

---

void : privatePropertyRemoved( DzProperty prop )

Signature:“privatePropertyRemoved(DzProperty*)”

Emitted when a private property is removed from this element.

Parameter(s):

• prop - The property just removed.

---

void : privatePropertyTreeChanged()

Signature:“privatePropertyTreeChanged()”

Emitted when the private property tree has changed.

---

void : propertyAdded( DzProperty prop )

Signature:“propertyAdded(DzProperty*)”

Emitted when a property is added to this element.

Parameter(s):

• prop - The property just added.

---

void : propertyListChanged()

Signature:“propertyListChanged()”

Emitted when a property is added to or removed from this element.

---

void : propertyListInTreeChanged()

---

void : propertyRemoved( DzProperty prop )

Signature:“propertyRemoved(DzProperty*)”

Emitted when a property is removed from this element.

Parameter(s):

• prop - The property just removed.

---

void : propertyTreeChanged()

Signature:“propertyTreeChanged()”

Emitted when the property tree has changed.