Class: TInternalAttribute

Declaration: Attribute.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TAttribute, MReferenceCounted

Inherited By:

TTaligentGUIPaints

Purpose:

TInternalAttribute is the base class for all attributes that are referred to by TSharedAttributes. To use this class, you must derive a new class from it and add fields representing the actual attribute data. This class is reference counted, and TInternalAttribute objects should be considered immutable. Objects of this class should be constructed in the constructor of an object that descends from TSharedAttribute, and should be given to the attribute manager which will take over ownership of the internal attribute object's storage.

Instantiation:

Always allocate on the heap.

Deriving Classes:

To use this class, you must derive a new class from it and add fields representing the actual attribute data. If the storage of an attribute is to be shared, then a new class must be derived from TSharedAttribute. Whenever a class is derived from TSharedAttribute a corresponding class must be derived from TInternalAttribute.

Concurrency:

Not multithread safe.

Resource Use:

This class is reference counted, and TInternalAttribute objects should be considered immutable. Objects of this class should be constructed in the constructor of an object that descends from TSharedAttribute, and should be given to the attribute manager which will take over ownership of the internal attribute object's storage. You are not responsible for deleting objects of class TInternalAttribute which have been passed to the attribute manager.

Member Function: TInternalAttribute::TInternalAttribute

TInternalAttribute ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

This constructor should never be called directly. To use this class, you must derive a new class from it and add fields representing the actual attribute data. Objects of this class should be constructed in the constructor of an object that descends from TSharedAttribute, and should be given to the attribute manager which will take over ownership of the internal attribute object's storage.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::~TInternalAttribute

virtual ~ TInternalAttribute ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Never call the destructor for this class directly. This class is reference counted, and TInternalAttribute objects should be considered immutable. Objects of this class should be constructed in the constructor of an object that descends from TSharedAttribute, and should be given to the attribute manager which will take over ownership of the internal attribute object's storage. You are not responsible for deleting objects of class TInternalAttribute which have been passed to the attribute manager.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Objects of this class are deleted automatically when the reference count goes to zero.

Member Function: TInternalAttribute::Finalize

virtual void Finalize ()

Interface Category:

API.

Purpose:

Allocates internal structures for the internal attribute just before it is added to the attribute manager. The default implementation does nothing. Every constructor of a class derived TSharedAttribute must allocate a new corresponding class derived from TInternalAttribute. The new internal attribute must be passed to the attribute manager by calling the non-virtual member function AdoptByManager. AdoptByManager tries to give the internal attribute to the attribute manager. If an internal attribute exists in the attribute manager that is identical to the newly created internal attribute, then the newly created internal attribute is deleted. Otherwise the member function Finalize is called. Thus, the Finalize member function allocates the internal structures for the internal attribute if and only if it is going to be adopted by the attribute manager.

Calling Context:

This function should only be used by the AdoptByManager member function. It gets called during streaming when the internal attribute gets added to the attribute manager. Be careful to ensure that all data required by Finalize is streamed in before Finalize can get called. Otherwise Finalize may try to evaluate data that hasn't yet been initialized.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::NamesMatch

bool NamesMatch (const TInternalAttribute * anotherAttribute) const

Interface Category:

API.

Purpose:

Compares the names and categories of two attributes.

Calling Context:

Called directly to determine if two attributes have the same name and category.

Parameters:

const TInternalAttribute * anotherAttribute -The attribute that the current object is to be compared to.

Return Value:

Returns true if the names and categories of the two attributes are the same.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::NamesAndValuesMatch

bool NamesAndValuesMatch (const TInternalAttribute * anotherAttribute) const

Interface Category:

API.

Purpose:

Compares the names, categories, and data of two attributes.

Calling Context:

Called directly to determine if two attributes have the same name, category, and internal data.

Parameters:

const TInternalAttribute * anotherAttribute -The attribute that the current object is to be compared to.

Return Value:

Returns true if the names, categories, and data of the two attributes are the same.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::Unreachable

virtual void Unreachable ()

Interface Category:

API.

Purpose:

When the reference count of an internal attribute goes to zero, this member function removes the internal attribute from the attribute manager, and deletes it. You can override this member function to clean up any attribute-specific storage contained in a derived class. When overriding Unreachable, be sure to call TInternalAttribute::Unreachable to have the internal attribute removed from the attribute manager and deleted.

Calling Context:

Called whenever the reference count of an internal attribute decreases to zero.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When overriding Unreachable, be sure to call TInternalAttribute::Unreachable to have the internal attribute removed from the attribute manager and deleted.

Member Function: TInternalAttribute::operator>>=

virtual TStream & operator >>=(TStream & toStream) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data

Parameters:

TStream & toStream -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::operator<<=

virtual TStream & operator <<= (TStream & fromStream)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromStream -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::SetName

virtual void SetName (const TToken & newName)

Interface Category:

API.

Purpose:

Sets the name associated with the attribute. The default implementation does nothing.

Calling Context:

This is a protected member function.

Parameters:

const TToken & newName -The new name to be associated with the attribute.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::SetCategory

virtual void SetCategory (const TToken & newCategory)

Interface Category:

API.

Purpose:

Sets the category associated with the attribute. The default implementation does nothing.

Calling Context:

This is a protected member function.

Parameters:

const TToken & newCategory -The new category to be associated with the attribute.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInternalAttribute::IsEqual

virtual bool IsEqual (const MCollectible * anotherAttribute) const

Interface Category:

API.

Purpose:

This virtual IsEqual member function is used to determine if an internal attribute already exists in the attribute manager that is identical to a newly created internal attribute. This function must be overridden by classes deriving from TInternalAttribute. This member function gets called during streaming to determine if an equivalent internal attribute already exists, so cyclical streaming is very dangerous. If the resurrection of an internal attribute causes other internal attributes to be resurrected, then unequal internal attributes may evaluate to equal when they are in an incomplete state. The result will be that shared attributes end up pointing to the wrong internal attributes, then horrible things will happen.

Calling Context:

Do NOT call this function directly. Use NamesAndValuesMatch to compare two attributes. The implementation of NamesAndValuesMatch uses this virtual IsEqual member function to determine equality.

Parameters:

const MCollectible * anotherAttribute -The internal attribute that this attribute is to be compared to.

Return Value:

Returns true if the data of the two internal attributes is the same. The default implementation simply returns true, since the data is specific to the derived class.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When overriding IsEqual, first use the inherited member function Attribute::NamesMatch to determine if the two objects have similar types.

Click the icon to mail questions or corrections about this material to Taligent personnel.