DzElement Class Reference
[Core Objects]

Base class for objects that have animatable/storable properties. More...

Inheritance diagram for DzElement:

DzBase QObject Object DzBackdrop DzMaterial DzModifier DzNode DzObject DzPoserJointParam DzPoserJointSphere DzShape DzWSModifier List of all members.

Methods

DzError addDataItem (DzElementData item)
DzError addPrivateProperty (DzProperty prop)
DzError addProperty (DzProperty prop)
void beginEdit ()
void cancelEdit ()
void clearAllAnimData ()
void clearAnimData (DzTimeRange range)
void copyFrom (DzElement source)
DzElementClipboard copyToClipboard ()
DzElementData findDataItem (String dataName)
DzProperty findPrivateProperty (String name)
DzProperty findPrivatePropertyByLabel (String label)
DzProperty findProperty (String name)
DzProperty findPropertyByLabel (String label)
void finishEdit ()
void getAttributes (DzSettings settings)
DzElementData getDataItem (Number index)
Array getDataItemList ()
DzElement getElementChild (Number which)
DzElement getElementParent ()
String getLabel ()
DzScript getLoadScript ()
Number getNumDataItems ()
Number getNumElementChildren ()
Number getNumPrivateProperties ()
Number getNumProperties ()
DzProperty getPrivateProperty (Number index)
DzPropertyGroupTree getPrivatePropertyGroups ()
Array getPrivatePropertyList ()
DzProperty getProperty (Number index)
DzPropertyGroupTree getPropertyGroups ()
Array getPropertyList ()
Boolean inEdit ()
DzError insertPrivateProperty (Number index, DzProperty prop)
DzError insertProperty (Number index, DzProperty prop)
Boolean isDataItemNameUnique (String dataName, Boolean makeUnique=false)
Boolean isPrivatePropertyNameUnique (String name, Boolean makeUnique=false)
Boolean isPropertyNameUnique (String name, Boolean makeUnique=false)
DzError movePrivateProperty (DzProperty prop, DzElement element)
DzError moveProperty (DzProperty prop, DzElement element)
DzError removeDataItem (DzElementData item)
DzError removePrivateProperty (String name)
DzError removePrivateProperty (DzProperty prop)
DzError removeProperty (String name)
DzError removeProperty (DzProperty prop)
DzElement setAttributes (DzSettings settings)
DzError setLabel (String name)
void setLoadScript (DzScript script)
void setName (String name)
void update ()

Public Member Functions

void Added (DzProperty prop)
void labelChanged (String newLabel)
 Signature: "labelChanged(const QString&)"
void ListChanged ()
void parentChanged ()
 Signature: "parentChanged()"
void privatePropertyAdded (DzProperty prop)
 Signature: "privatePropertyAdded(DzProperty*)"
void privatePropertyListChanged ()
 Signature: "privatePropertyListChanged()"
void privatePropertyRemoved (DzProperty prop)
 Signature: "privatePropertyRemoved(DzProperty*)"
void privatePropertyTreeChanged ()
 Signature: "privatePropertyTreeChanged()"
void Removed (DzProperty prop)
void TreeChanged ()

Detailed Description

Base class for objects that have animatable/storable properties.

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.


Member Function Documentation

DzError DzElement::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.

Parameters:
item The data item to attach to this element.
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
removeDataItem()

DzError DzElement::addPrivateProperty ( DzProperty  prop  ) 

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

Parameters:
newprop A pointer to the property to add to the element
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
removeProperty()

DzError DzElement::addProperty ( DzProperty  prop  ) 

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

Parameters:
newprop A pointer to the property to add to the element
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
removeProperty()

void DzElement::beginEdit (  ) 

Begins an editing operation for this element - DzProperty::beginEdit() will be called for all properties belonging to this element. Subclasses should reimplement this function to provide additional editing behavior.

Reimplemented in DzNode, and DzPoserJointParam.

void DzElement::cancelEdit (  ) 

Cancels an editing operation for this element - DzProperty::cancelEdit() will be called for all properties belonging to this element. Subclasses should reimplement this function to provide additional editing behavior.

Reimplemented in DzNode, and DzPoserJointParam.

void DzElement::clearAllAnimData (  ) 

Removes all animation keys on this object.

void DzElement::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.

Parameters:
range The range of time over which keys will be removed.

void DzElement::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.

Parameters:
source The element that this element should copy property values from.

DzElementClipboard DzElement::copyToClipboard (  ) 

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. Subclasses should reimplement this function if they contain non-property information or other implementation specific data that needs to be copied.

Returns:
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.

DzElementData DzElement::findDataItem ( String  dataName  ) 

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

Parameters:
dataName Unique ID to use in looking up the user data item.
Returns:
The corresponding item if found, NULL if no match.

DzProperty DzElement::findPrivateProperty ( String  name  ) 

Locate a property by name.

Parameters:
name Name of the property to search for.
Returns:
A pointer to the property, or NULL if not found.

DzProperty DzElement::findPrivatePropertyByLabel ( String  label  ) 

Locate a property by label.

Parameters:
label Label of the property to search for.
Returns:
A pointer to the property, or NULL if not found.

DzProperty DzElement::findProperty ( String  name  ) 

Locate a property by name.

Parameters:
name Name of the property to search for.
Returns:
A pointer to the property, or NULL if not found.

DzProperty DzElement::findPropertyByLabel ( String  label  ) 

Locate a property by label.

Parameters:
label Label of the property to search for.
Returns:
A pointer to the property, or NULL if not found.

void DzElement::finishEdit (  ) 

finishes an editing operation for this element - DzProperty::finishEdit() will be called for all properties belonging to this element. Subclasses should reimplement this function to provide additional editing behavior.

Reimplemented in DzNode, and DzPoserJointParam.

void DzElement::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. See also setAttributes.

DzElementData DzElement::getDataItem ( Number  index  ) 

Parameters:
index The index of the data item to return.
Returns:
A pointer to the data item for this element at the given index

Array DzElement::getDataItemList (  ) 

Returns:
A list of the data items attached to this element

DzElement DzElement::getElementChild ( Number  which  ) 

Parameters:
which The index of the child element to return.
Returns:
A pointer to the child of this element at the given index

DzElement DzElement::getElementParent (  ) 

Returns:
A pointer to the element that is the parent of this element. Null if the element has no parent.

String DzElement::getLabel (  ) 

Returns:
The user-defined interface label for this object.

DzScript DzElement::getLoadScript (  ) 

Returns:
A pointer to the script that is executed when this element is loaded from a file.

Number DzElement::getNumDataItems (  ) 

Returns:
The number of user data items attached to this element

Number DzElement::getNumElementChildren (  ) 

Returns:
The number of children this element has

Number DzElement::getNumPrivateProperties (  ) 

Get the number of private properties for this element

Returns:
The number of properties currently owned by this element.

Number DzElement::getNumProperties (  ) 

Get the number of properties for this element

Returns:
The number of properties currently owned by this element.

DzProperty DzElement::getPrivateProperty ( Number  index  ) 

Get a property from this element's property list

Parameters:
i Index of the property to return
Returns:
A pointer to the property at the given index

DzPropertyGroupTree DzElement::getPrivatePropertyGroups (  ) 

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

QObjectList DzElement::getPrivatePropertyList (  ) 

This function is provided for DAZ Script access. Plugin developers are encouraged to use the much more efficient propertyListIterator() method.

Returns:
A QObjectList of all the properties on this element.

DzProperty DzElement::getProperty ( Number  index  ) 

Get a property from this element's property list

Parameters:
i Index of the property to return
Returns:
A pointer to the property at the given index

DzPropertyGroupTree DzElement::getPropertyGroups (  ) 

Returns:
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.

QObjectList DzElement::getPropertyList (  ) 

This function is provided for DAZ Script access. Plugin developers are encouraged to use the much more efficient propertyListIterator() method.

Returns:
A QObjectList of all the properties on this element.

Boolean DzElement::inEdit (  ) 

Returns:
True if the element is in an editing operation.
See also:
beginEdit(), finishEdit(), cancelEdit()

DzError DzElement::insertPrivateProperty ( Number  index,
DzProperty  prop 
)

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

Parameters:
newprop A pointer to the property to add to the element
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
removeProperty()

DzError DzElement::insertProperty ( Number  index,
DzProperty  prop 
)

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

Parameters:
index The index in the properties list to insert the property.
prop A pointer to the property to insert in the element
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
addProperty(), removeProperty()

Boolean DzElement::isDataItemNameUnique ( String  name,
Boolean  makeUnique = false 
)

Parameters:
name The name to test for uniqueness.
makeUnique If true, the value of name will be changed to make it unique.
Returns:
true if the given name is not already used by a data item attached to this element

Boolean DzElement::isPrivatePropertyNameUnique ( String  name,
Boolean  makeUnique = false 
)

Given the name of a property, makes sure the name is currently unique for this element. If it is not and makeUnique is true, this method modifies the name to make it unique.

Parameters:
name The name to test for uniqueness.
makeUnique If true, the value of name will be modified to make it unique.
Returns:
true if the name is unique, otherwise false

Boolean DzElement::isPropertyNameUnique ( String  name,
Boolean  makeUnique = false 
)

Given the name of a property, makes sure the name is currently unique for this element. If it is not and makeUnique is true, this method modifies the name to make it unique.

Parameters:
name The name to test for uniqueness.
makeUnique If true, the value of name will be modified to make it unique.
Returns:
true if the name is unique, otherwise false

void DzElement::labelChanged ( String  newLabel  ) 

Signature: "labelChanged(const QString&)"

Emitted when this object's label is changed

Parameters:
newLabel The new label of the element.

DzError DzElement::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.

Parameters:
prop A pointer to 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 A pointer to the element that prop should be moved to
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
addProperty()

DzError DzElement::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.

Parameters:
prop A pointer to 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 A pointer to the element that prop should be moved to
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
addProperty()

void DzElement::parentChanged (  ) 

Signature: "parentChanged()"

Emitted when this element's parent is changed

void DzElement::privatePropertyAdded ( DzProperty  prop  ) 

Signature: "privatePropertyAdded(DzProperty*)"

Emitted when a private property is added to this element

Parameters:
prop A pointer the the property just added

void DzElement::privatePropertyListChanged (  ) 

Signature: "privatePropertyListChanged()"

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

void DzElement::privatePropertyRemoved ( DzProperty  prop  ) 

Signature: "privatePropertyRemoved(DzProperty*)"

Emitted when a private property is removed from this element

Parameters:
prop A pointer the the property just removed

void DzElement::privatePropertyTreeChanged (  ) 

Signature: "privatePropertyTreeChanged()"

Emitted when the private property tree has changed

DzError DzElement::removeDataItem ( DzElementData  item  ) 

Remove the data item from this element.

Parameters:
item A pointer to the data item to remove.
Returns:
DZ_NO_ERROR on success.
See also:
addDataItem()

DzError DzElement::removePrivateProperty ( String  name  ) 

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

Parameters:
name Name of the property to search for and remove if it is found.
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
addProperty()

DzError DzElement::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.

Parameters:
prop A pointer to the property to remove from the element
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
addProperty()

DzError DzElement::removeProperty ( String  name  ) 

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

Parameters:
name Name of the property to search for and remove if it is found.
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
addProperty()

DzError DzElement::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.

Parameters:
prop A pointer to the property to remove from the element
Returns:
DZ_NO_ERROR on success, otherwise an appropriate error code.
See also:
addProperty()

void 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. The caller is responsible for cleaning up the memory of the reutrn element it it is not this.

Default implementation returns this with no changes.

void DzElement::setLabel ( String  name  ) 

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

Parameters:
name The new label for the element.

Reimplemented in DzPoserJointParam.

void DzElement::setLoadScript ( DzScript  script  ) 

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

Parameters:
script A pointer to the script that will be saved with this element and executed when it is loaded from file. The element takes ownership of this pointer.

void DzElement::setName ( String  name  ) 

Set the internal name of this object.

Parameters:
name The name to assign to this element

void DzElement::update (  ) 

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


Generated on Thu Sep 24 12:21:11 2009

Copyright © 2002 - 2009 DAZ 3D, Inc.