Base class for objects that have animatable/storable properties.

More...

Inherits :

• QObject
  • DzBase

Inherited By : DzBackdrop, DzBoneBinding, bulgebinding_dz, geometryregion_dz, iraypropertyholder_dz, DzLegacyAlternateGeometry, legacyjoint_dz, legacyjointparam_dz, DzMaterial, DzModifier, DzNode, DzObject, DzShaderBrick, DzShape, DzSimulationSettingsProvider and DzWeightMap

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 of time, or over all time.

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

---

: NameEditScope

Values that represent the intended scope (if any) at which the name of an element, or its constituent parts, is exposed to the user for editing.

Since:

• 4.12.1.103

• NoNameEdit - Editing the name of this element, and any of its constituent parts, is not intended to be exposed to the user.
• ElementNameEdit - The name of the element is intended to be exposed to the user for editing.
• PropertyNameEdit - The names of individual properties are intended to be exposed to the user for editing.

---

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 )

Adds a new private property to this element 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:

• removePrivateProperty()

---

DzError : addProperty( DzProperty prop )

Adds a new property to this element 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 set on the properties of this element.

---

void : clearAnimData( DzTimeRange range )

Clears 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 element.

---

DzError : deleteDataItem( DzElementData item )

Remove the data item from this element and deletes it.

Parameter(s):

• item - The data item to remove. The item is invalid after this call if DZ_NO_ERROR is returned.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addDataItem()

---

DzElementData : findDataItem( String dataName )

Parameter(s):

• dataName - The name of the user data item to find.

Return Value:

• The data item with the given name (if any), otherwise null.

---

Number : findDataItemIndex( DzElementData item )

Parameter(s):

• item - The data item to find.

Return Value:

• The first index of the data item (if any), otherwise -1.

---

DzProperty : findMatchingProperty( DzProperty srcProp )

Parameter(s):

• srcProp - The property to search for a match.

Return Value:

• The matching property (if any), otherwise null.

---

DzProperty : findPrivateProperty( String name )

Parameter(s):

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

Return Value:

• The private property with the given name (if any), otherwise null.

---

DzProperty : findPrivateProperty( String name, Boolean caseSensitive )

Parameter(s):

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

Return Value:

• The private property with the given name (if any), otherwise null.

---

DzProperty : findPrivatePropertyByLabel( String label )

Parameter(s):

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

Return Value:

• The private property with the given label (if any), otherwise null.

---

DzProperty : findPrivatePropertyByLabel( String label, Boolean caseSensitive )

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 with the given label (if any), otherwise null.

---

DzProperty : findProperty( String name )

Locate a property by name.

Parameter(s):

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

Return Value:

• The property with the given name (if any), otherwise null.

---

DzProperty : findProperty( String name, Boolean caseSensitive )

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 with the given name (if any), otherwise null.

---

DzProperty : findPropertyByLabel( String label, Boolean caseSensitive )

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 with the given label (if any), otherwise null.

---

DzProperty : findPropertyByLabel( String label )

Parameter(s):

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

Return Value:

• The property with the given label (if any), otherwise null.

---

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.

See Also:

• getNumDataItems()

---

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 (if any), otherwise null.

---

DzElement : getElementParent()

Return Value:

• The element that is the parent of this element (if any), otherwise null.

---

String : getLabel()

Return Value:

• The user-facing label for this element.

---

DzScript : getLoadScript()

Return Value:

• The script that is executed when this element is loaded from a file (if any), otherwise null.

---

NameEditScope : getNameEditScope()

Return Value:

• The value that represents the intended scope (if any) at which the name of this element, or its constituent parts, is exposed to the user for editing.

Since:

• 4.12.1.103

---

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 )

Parameter(s):

• i - The index of the property to get.

Return Value:

• The private property at the given index (if valid), otherwise null.

---

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 private properties on this element.

---

DzProperty : getProperty( Number index )

Parameter(s):

• i - The index of the property to get.

Return Value:

• The property at the given index (if valid), otherwise null.

---

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 properties on this element.

---

String : getTypeLabel()

Return Value:

• The user-facing label for this type of element.

Since:

• 4.12.1.103

---

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 private property to this element 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:

• addPrivateProperty(
• removePrivateProperty()

---

DzError : insertProperty( Number index, DzProperty prop )

Adds a new property to this element 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:

• DZ_NO_ERROR on success, otherwise an appropriate 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 (i.e., DzProperty::isUserProperty()). 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:

• addPrivateProperty()

---

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 private property, if it can be removed. Properties can be specified as non-removable (i.e., DzProperty::isUserProperty() - e.g. the rotation channels of the DzNode class). Doing so makes it impossible to remove that property from this element.

Parameter(s):

• prop - The property to remove from the element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate error code.

See Also:

• addPrivateProperty()

---

DzError : removePrivateProperty( String name )

Attempts to remove the named property. Fails if the property could not be found or could not be removed (i.e., DzProperty::isUserProperty()).

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:

• addPrivateProperty()

---

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()

---

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 element.

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()

---

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 )

Sets the user-facing label (i.e., displayed in the interface) for this element.

Parameter(s):

• name - The new label for this element.

Return Value:

• DZ_NO_ERROR on success, otherwise an appropriate 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. This element takes ownership.

Attention:

• A global transient function named element, whose return value refers to this element when called within script, is provided to the script in the global context at runtime. Attempts to use this global function outside of this context will result in a ReferenceError.

See Also:

• DzSimpleElementScriptData

---

void : setName( String name )

Sets the internal name of this element.

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 element.

---

void : labelChanged( String newLabel )

Signature:“labelChanged(const QString&)”

Emitted when this element'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()

Signature:“privatePropertyListInTreeChanged()”

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

---

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()

Signature:“propertyListInTreeChanged()”

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

---

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.