Class: TAttributeGroupHandle

Declaration: AttributeGroup.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TAttributeGroup

Inherited By:

TInheritableGroupHandle

Purpose:

This class refers to an object of class TInternalAttributeGroup, and is notified (its NotifyChanged member function is called) whenever a change is made to the internal attribute group that it refers to. There can be any number of TAttributeGroupHandle objects referring to a TInternalAttributeGroup object. Allocating an object of this class automatically creates an object of class TInternalAttributeGroup if you use the empty constructor, or adds a reference to an existing TInternalAttributeGroup object if you use the copy constructor or the assignment operator.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a concrete class for implementing surrogate attribute groups. Use this class or one of the derived classes whenever you want to create or use an attribute group: do not allocate an TInternalAttributeGroup directly. The principal derived class is TInheritableGroupHandle which adds support for a hierarchy of reference counted internal attribute groups.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TAttributeGroupHandle::TAttributeGroupHandle

TAttributeGroupHandle ()
TAttributeGroupHandle (bool NotifyChanged)
TAttributeGroupHandle (const TAttributeGroupHandle & copyFrom)

Interface Category:

API.

Purpose:

Default constructor. Automatically creates an TInternalAttributeGroup object. This constructor turns notification on, so the NotifyChanged member function will get called whenever the internal attribute group is changed.
This constructor is used to indicate that the new attribute group handle should not be notified when the internal attribute group is changed.
Copy constructor. Adds a reference to an existing TInternalAttributeGroup object.

Calling Context:

Called by the stream-in operators and to create a new attribute group.
Called directly to create a new attribute group handle which will not be notified when the internal attribute group is changed.
Called to copy an object.

Parameters:

Takes no parameters.
bool NotifyChanged -The Boolean to indicate if notification is to be turned on or off. true indicates that notification is to be turned on. false indicates that notification is to be turned off.
const TAttributeGroupHandle & 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.

Member Function: TAttributeGroupHandle::~TAttributeGroupHandle

virtual ~ TAttributeGroupHandle ()

Interface Category:

API.

Purpose:

Destructor. Decreases the reference count of the corresponding internal attribute group by one.

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: TAttributeGroupHandle::DeepCopy

virtual TAttributeGroup * DeepCopy ()

Interface Category:

API.

Purpose:

Clones the attribute group handle and the internal 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 handle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The user is responsible for deleting the resulting attribute group handle.

Member Function: TAttributeGroupHandle::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: TAttributeGroupHandle::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.

TInternalAttributeGroup

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: TAttributeGroupHandle::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. Note: This is a wrapper which calls the same member function on the internal attribute group.

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: TAttributeGroupHandle::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. Note: This is a wrapper which calls the same member function on the internal attribute 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: TAttributeGroupHandle::Count

virtual long Count () const

Interface Category:

API.

Purpose:

Returns the number of elements in this attribute group. Note: This is a wrapper which calls the same member function on the internal 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: TAttributeGroupHandle::Delete

virtual void Delete (const TAttribute & anAttribute)

Interface Category:

API.

Purpose:

Removes the specified attribute from this attribute group and deletes it. This member function calls NotifyChanged to propagate change notification. Note: This is a wrapper which calls the same member function on the internal attribute group.

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: TAttributeGroupHandle::DeleteAll

virtual void DeleteAll ()

Interface Category:

API.

Purpose:

Deletes all of the attributes in this attribute group. This member function calls NotifyChanged to propagate change notification. Note: This is a wrapper which calls the same member function on the internal attribute group.

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: TAttributeGroupHandle::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. Note: This is a wrapper which calls the same member function on the internal 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: TAttributeGroupHandle::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. Note: This is a wrapper which calls the same member function on the internal attribute group.

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: TAttributeGroupHandle::GetParent

virtual TAttributeGroup * GetParent () const

Interface Category:

API.

Purpose:

Returns a pointer to this attribute group's parent group. Note: This is a wrapper which calls the same member function on the internal attribute 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: TAttributeGroupHandle::SetParent

virtual void SetParent (TAttributeGroup * myNewParent)

Interface Category:

API.

Purpose:

Sets the parent group pointer to point to the specified group. This member function calls NotifyChanged to propagate change notification. Note: This is a wrapper which calls the same member function on the internal attribute group.

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 is not checked. This means that calling SetParent with a group that already exists in the hierarchy results in an infinite loop.

Member Function: TAttributeGroupHandle::NotifyChanged

virtual void NotifyChanged ()

Interface Category:

API.

Purpose:

Notifies all dependent attribute groups that this group has changed. Override this member function to provide behavior such as redrawing or reformatting as a result of change notification.

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: TAttributeGroupHandle::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. Note: This is a wrapper which calls the same member function on the internal attribute group.

Calling Context:

Called 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: TAttributeGroupHandle::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. Note: This is a wrapper which calls the same member function on the internal attribute group.

Calling Context:

Use this member function 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: TAttributeGroupHandle::ChangesPending

virtual bool ChangesPending ()

Interface Category:

API.

Purpose:

Returns the value of the flag that is used to indicate if notification is currently postponed. Note: This is a wrapper which calls the same member function on the internal attribute group.

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: TAttributeGroupHandle::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. Note: This is a wrapper which calls the same member function on the internal attribute group.

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: TAttributeGroupHandle::operator=

TAttributeGroupHandle & operator =(const TAttributeGroupHandle & group)

Interface Category:

API.

Purpose:

Assignment operator. Sets the internal attribute group pointer of this TAttributeGroupHandle to be the same as that of the given TAttributeGroupHandle.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TAttributeGroupHandle & group -The TAttributeGroupHandle from which to copy the internal attribute group pointer.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroupHandle::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: TAttributeGroupHandle::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: TAttributeGroupHandle::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 member function should not be used by any other classes and frameworks. It should only be used by 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: TAttributeGroupHandle::SetInternalAttributeGroup

void SetInternalAttributeGroup (TInternalAttributeGroup * aRealGroup)

Interface Category:

API.

Purpose:

Sets the internal attribute group pointer to the one passed as an argument. Checks to see if the current internal attribute group pointer is the same as the one being passed in, and if so, does nothing. If the old internal attribute group pointer is not the same as the new one, the reference count on the old group is decremented and the reference count on the new internal attribute group is incremented and the pointer for this group is set to the new internal attribute group.

Calling Context:

This is a protected member function.

Parameters:

TInternalAttributeGroup * aRealGroup -The internal attribute group that this attribute group handle is to point to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAttributeGroupHandle::GetNotification

bool GetNotification ()

Interface Category:

API.

Purpose:

Indicates if the NotifyChanged member function will get called when the internal attribute group has been changed.

Calling Context:

Called directly to determine if the NotifyChanged member function will get called when the internal attribute group has been changed.

Parameters:

Takes no parameters.

Return Value:

Returns true if the notification mechanism is turned on. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None

Member Function: TAttributeGroupHandle::SetNotification

virtual void SetNotification (bool NotifyChanged)

Interface Category:

API.

Purpose:

Specifies if the NotifyChanged member function is to get called when the internal attribute group has been changed.

Calling Context:

Called to turn notification on or off.

Parameters:

bool NotifyChanged -The Boolean to indicate if notification is to be turned on or off. true indicates that notification is to be turned on. false indicates that notification is to be turned off.

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.