Class: TAttributeGroup

Declaration: AttributeGroup.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TAttributeGroupHandle TSimpleAttributeGroup TViewGroupHandle

Purpose:

Attribute groups are collections of attributes. The class TAttributeGroup is an abstract base class representing the protocol for all attribute grouping mechanisms. Attribute groups operate on the attributes they manage via set semantics. That is, one queries for the existence of a particular attribute in an attribute group by reference or example, rather than by name.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Most of the member functions in this base class are purely virtual. The principal derived classes are as follows: TSimpleAttributeGroup is useful when shared groups and dynamic inheritance are not needed; TAttributeGroupHandle is useful when many clients wish to share the same group of attributes, and each client wishes to know when a change is made to the group; TInheritableGroupHandle is useful when a hierarchy of attribute groups, each one shareable, is appropriate.

Concurrency:

Not multithread safe.

Resource Use:

All attribute groups clone attributes before adding them to the group. Therefore, attribute groups always own the storage associated with the attributes they contain.

Member Function: TAttributeGroup::~TAttributeGroup

virtual ~ TAttributeGroup ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::DeepCopy

virtual TAttributeGroup * DeepCopy ()

Interface Category:

API.

Purpose:

Clones the attribute group.

Calling Context:

Called directly to copy an attribute group and its contents.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the new attribute group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The user is responsible for deleting the resulting attribute group.

Member Function: TAttributeGroup::Member

virtual TAttribute * Member (const TAttribute & anAttribute, EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents) const
virtual bool Member (const TAttributeGroup & anAttributeGroup, EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents) const

Interface Category:

API.

Purpose:

Determines if the given attribute is in this attribute group.
Returns true if the given set of attributes are all members of this group.

Calling Context:

Called directly to determine if a specified attribute or group of attributes is contained in an attribute group.

Parameters:

const TAttribute & anAttribute -The attribute that you are looking for.
EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents -Indicates which groups in an attribute group hierarchy to look in for the given attribute. The default is to look in the local group and all of its parent groups.
const TAttributeGroup & anAttributeGroup -The set of attributes to search for.
EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents -Indicates which groups in an attribute group hierarchy to look in for the given attribute. The default is to look in the local group and all of its parent groups.

Return Value:

If there is an attribute in the group that is equivalent to the given attribute, then a pointer to the similar attribute is returned.
Returns true if the given set of attributes are all members of this group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::Add

virtual void Add (const TAttribute & anAttribute)
virtual void Add (const TAttributeGroup & aGroup)

Interface Category:

API.

Purpose:

Adds a copy of the given attribute to this attribute group.
Adds a copy of each attribute in the given group to this attribute group, replacing any duplicates. Only attributes in the given group are added. Attributes that are only inherited through the parent chain are not added.

Calling Context:

Called directly to add an attribute or group of attributes to an attribute group.

Parameters:

const TAttribute & anAttribute -The attribute to add to this group.
const TAttributeGroup & aGroup -The set of attributes to add to this group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::AddAllInherited

virtual void AddAllInherited (const TAttributeGroup & aGroup)

Interface Category:

API.

Purpose:

Copies of all of the attributes in the specified group, including those in the parent chain for that group, and adds the copied attributes to the current attribute group. Duplicates are replaced.

Calling Context:

Called directly to add attributes from one group and all of the groups in its parent chain into another group.

Parameters:

const TAttributeGroup & aGroup -The set of attributes to add to this group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::Count

virtual long Count () const

Interface Category:

API.

Purpose:

Returns the number of elements in this attribute group.

Calling Context:

Called directly to determine the number of attributes contained in an attribute group.

Parameters:

Takes no parameters.

Return Value:

Returns the number of elements in this attribute group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::CountAllInherited

virtual long CountAllInherited () const

Interface Category:

API.

Purpose:

Returns the number of elements in this group and all of its ancestors. CountAllInherited calls the member function GetAllInheritedAttributes and returns the number of elements in the resulting group.

Calling Context:

Called directly to determine the number of attributes contained in an attribute group and all of the attribute groups in its parent chain.

Parameters:

Takes no parameters.

Return Value:

Returns the number of elements in this group and all of its ancestors.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is an expensive operation.

Member Function: TAttributeGroup::Delete

virtual void Delete (const TAttribute & anAttribute)

Interface Category:

API.

Purpose:

Removes the specified attribute from this attribute group and deletes it. Note: When notification is turned on, this member function calls NotifyChanged to propagate change notification.

Calling Context:

Called directly to remove an attribute from an attribute group and delete it.

Parameters:

const TAttribute & anAttribute -The attribute to be removed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::DeleteAll

virtual void DeleteAll ()

Interface Category:

API.

Purpose:

Deletes all of the attributes in this attribute group. Note: When notification is turned on, this member function calls NotifyChanged to propagate change notification.

Calling Context:

Called directly to remove and delete all of the attributes from an attribute group.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::GetParent

virtual TAttributeGroup * GetParent () const

Interface Category:

API.

Purpose:

Returns a pointer to this attribute group's parent group.

Calling Context:

Called directly to get a pointer to an attribute group's parent group.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to this attribute group's parent group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::SetParent

virtual void SetParent (TAttributeGroup * myNewParent)

Interface Category:

API.

Purpose:

Sets the parent group pointer to point to the specified group. Note: When notification is turned on, this member function calls NotifyChanged to propagate change notification.

Calling Context:

Called directly to set the attribute group's parent group.

Parameters:

TAttributeGroup * myNewParent -The attribute group that is to become the parent of this attribute group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

To improve performance, multiple occurrences of the same group in an attribute group hierarchy are not checked for. This means that calling SetParent with a group that already exists in the hierarchy results in an infinite loop.

Member Function: TAttributeGroup::GetAllInheritedAttributes

virtual void GetAllInheritedAttributes (TSetOf < TAttribute > & fillIn) const

Interface Category:

API.

Purpose:

Builds an attribute group consisting of all attributes that are anywhere in this attribute group and this group's parent chain.

Calling Context:

Called to get a collection of all of the attributes that are contained anywhere in an attribute group and its parent chain.

Parameters:

TSetOf < TAttribute > & fillIn -The attribute group that is to be filled in with all of the attributes that are anywhere in this attribute group and this group's parent chain.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The attributes in the resulting set are owned by the attribute group. They are not to be deleted.

Member Function: TAttributeGroup::CreateIterator

virtual TIteratorOver < TAttribute > * CreateIterator () const

Interface Category:

API.

Purpose:

Creates and returns an iterator that only iterates over the contents of this attribute group.

Calling Context:

Called directly to create an iterator to iterate over the attributes in an attribute group.

Parameters:

Takes no parameters.

Return Value:

A pointer to an iterator that only iterates over the contents of this attribute group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The user of this member function is responsible for deleting the iterator that is returned.

Member Function: TAttributeGroup::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: TAttributeGroup::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: TAttributeGroup::NotifyChanged

virtual void NotifyChanged ()

Interface Category:

API.

Purpose:

Notifies all dependent attribute groups that this group has changed.

Calling Context:

Called when notification is turned on and this attribute group has been changed (something added or removed).

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::BeginChanges

virtual void BeginChanges ()

Interface Category:

API.

Purpose:

There is a changes pending flag which is used to prevent notification when a batch of changes is to be made to an attribute group. This member function sets this flag to true to indicate that a batch of changes is about to be made, and that change notification should be postponed until after the changes has been made.

Calling Context:

Call to prevent notification on each change in a batch of changes to an attribute group.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::EndChanges

virtual void EndChanges ()

Interface Category:

API.

Purpose:

Calls NotifyChanged to propagate change notification, and resets the changes pending flag to false so notification will no longer be postponed.

Calling Context:

Call when you have finished doing a batch of changes to an attribute group. This member function calls the NotifyChanged member function so that all dependent attribute groups will be notified that the group has changed.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::ChangesPending

virtual bool ChangesPending ()

Interface Category:

API.

Purpose:

Returns the value of the flag that is used to indicate if notification is currently postponed.

Calling Context:

Called directly to determine if notification is currently postponed on the attribute group.

Parameters:

Takes no parameters.

Return Value:

Returns true if notification is currently postponed for the attribute group. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::SetChangesPending

virtual void SetChangesPending (bool pending)

Interface Category:

API.

Purpose:

Sets the value of the flag that is used to indicate if notification is currently postponed. Setting the flag to true indicates that notification is to be postponed, and setting the flag to false indicates that notification is no longer postponed.

Calling Context:

Called directly to change the value of the flag that indicates if change notification is currently postponed for an attribute group.

Parameters:

bool pending -The value that the changes pending flag is to be set to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::GetInternalAttributeGroup

virtual TInternalAttributeGroup * GetInternalAttributeGroup () const

Interface Category:

API.

Purpose:

Returns a pointer to the internal attribute group for this attribute group handle.

Calling Context:

This function should only be used within the implementation of classes that are derived from TAttributeGroupHandle.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the internal attribute group for this attribute group handle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroup::TAttributeGroup

TAttributeGroup ()
TAttributeGroup (const TAttributeGroup & copyFrom)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

This is an abstract base class, so the constructors for this class should never be called directly.

Parameters:

Takes no parameters.
const TAttributeGroup & copyFrom -The attribute group to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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