AlClusterable

Synopsis

#include <AlClusterable.h>

class AlClusterable

virtual AlCluster*	firstCluster() const;

virtual AlCluster*	nextCluster( const AlCluster* ) const;

virtual AlCluster*	prevCluster( const AlCluster* ) const;

virtual statusCode	nextClusterD( AlCluster* ) const;

virtual statusCode	prevClusterD( AlCluster* ) const;

virtual statusCode	applyIteratorToClusters( AlIterator*, int& );

statusCode	addToCluster( AlCluster*, double = 1.0 );

statusCode	removeFromCluster( AlCluster* );

statusCode	removeFromAllClusters();

AlClusterMember*	isClusterMember( AlCluster* ) const;

double	percentEffect( AlCluster* ) const;

statusCode	setPercentEffect( AlCluster*, double );

Description

This class is a base class for all objects which can be contained in a cluster. It provides the methods necessary to access the cluster methods of these objects.

AlCluster* AlClusterable::firstCluster() const

Description

Finds and returns the first cluster of which this object is a member. If no such cluster can be found, NULL is returned.

AlCluster* AlClusterable::nextCluster( const AlCluster* lastCluster ) const

Description

Finds and returns the cluster following the given one of which this object is a member. If no such cluster can be found, NULL is returned.

Argument

< lastCluster - cluster to walk forward from

AlCluster* AlClusterable::prevCluster( const AlCluster* lastCluster ) const

Description

Finds and returns the cluster preceding the given one of which this object is a member. If no such cluster can be found, NULL is returned.

Argument

< lastCluster - cluster to walk forward from

statusCode AlClusterable::nextClusterD( AlCluster* lastCluster ) const

Description

Destructively sets the passed-in cluster to the next cluster for the given object. If this can not be accomplished, the passed-in cluster is unaffected.

Argument

< lastCluster - cluster to walk forward from

Return Codes

sSuccess - the cluster now points to the next cluster

sInvalidArgument - ’lastCluster’ was invalid or NULL

sFailure - there was no next cluster

statusCode AlClusterable::prevClusterD( AlCluster* lastCluster ) const

Description

Finds and returns the cluster preceding the given one of which this object is a member. If no such cluster can be found, NULL is returned.

Argument

< lastCluster - cluster to walk forward from

Return Codes

sSuccess - the cluster now points to the previous cluster

sInvalidArgument - ’lastCluster’ was invalid or NULL

sFailure - there was no previous cluster

statusCode AlClusterable::applyIteratorToClusters( AlIterator* iter, int &rc )

Description

Applies the given iterator to all the clusters in this object. See the documentation for AlIterator.

Warning: be careful when using this iterator. If you modify the actual cluster during an iteration, it is possible that this routine will end up pointing to invalid data and send you garbage. This should not happen when simply applying transformations to a cluster. But deleting a cluster using this method is considered unsafe. If you do it, return immediately.

Arguments

< iter - the iterator to apply to each cluster

> rc - the return from the last application of the iterator

Return Codes

sSuccess - the application of the iterator terminated normally

sFailure - the application of the iterator terminated abnormally

sInvalidArgument - the iterator was NULL

double AlClusterable::percentEffect( AlCluster* cluster ) const

Description

Returns the percentage effect the given cluster has on this object. If the call fails, 0.0 is returned.

Arguments

< cluster - the cluster whose percentage effect is to be found

statusCode AlClusterable::setPercentEffect( AlCluster* cluster, double percentage )

Description

Sets the percentage effect the given cluster has on all things below this object.

Arguments

< cluster - the object whose children are to have their cluster percentage effects set

Return Codes

sSuccess - method was successful

sInvalidArgument - ’clustobj’ was NULL

sFailure - the percentage effect setting failed

sInvalidObject - the cluster was not valid

statusCode AlClusterable::addToCluster( AlCluster* cluster, double percentage )

Description

Adds this clusterable object to a cluster. This means that all CVs under this DAG are affected by the cluster. The percentage defines how much of the cluster’s transformation is applied to the CVs under the DAG node. The default value of 1.0 means that the object’s CVs are affected 100% by the cluster leaf transformations.

The method may fail if unable to create a cluster member object, or if the addition of the object would create a cycle of clusters, or if the object to be added is already in the cluster, or if the object to be added already has an ancestor in the same target cluster.

Arguments

< cluster - the cluster to add this object to

< percentage - the extent of the effect of the cluster on the object’s CVs. The default is 1.0 (100%).

Return Codes

sSuccess - everything was successful

sInvalidArgument - cluster was NULL

sFailure - failed for one of the reasons outlined above

sInvalidObject - the cluster was invalid

sInsufficientMemory - not enough memory

statusCode AlClusterable::removeFromCluster( AlCluster* cluster )

Description

Removes this object from the cluster.

Arguments

< cluster - the cluster to remove this object from.

Return Codes

sSuccess - everything was successful

sInvalidObject - the cluster is not valid

sInvalidArgument - clustobj was not valid

AlClusterMember* AlClusterable::isClusterMember( AlCluster* cluster ) const

Description

Finds the AlClusterMember that corresponds to the relationship between this object and the cluster object. NULL is returned if the object is not a member of the cluster or the cluster is not valid.

Arguments

< cluster - the cluster object to be checked

statusCode AlClusterable::removeFromAllClusters()

Description

Removes this object from all clusters in the universe that it may be in.

Return Codes

sSuccess - the object was successfully removed from all clusters

sInvalidArgument - the object was not valid