Encapsulates
methods common to Alias objects that can belong to clusters.
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
